Search returns nothing

​

Signs

• penumbra files search "<query>" prints no passages and the line No passages match "<query>"., followed by a hint.
• The first line reads like mode: hybrid -> lexical; semantic coverage: none (0/4).
• penumbra search "<query>" prints files: 0 passages and Nothing matched.
• MCP: omnisearch prints a line that starts with Files: no relevant results when it left out weak matches. The line says how many.
• You saw the File in penumbra files list, and the search still skips it.

​

Why it happens

One empty result has several causes. Each cause is a different step in the chain from File to answer.

• Your words. Search by exact words needs every plain word of the query in one passage. A word from another passage gives no match. The name, tags and description of the File count as part of each passage. Penumbra also reduces words to a base form and ignores very common words.
• The File. Search reads only the current version of a live File that is ready. A File in the trash, a File that is still processing, a File that failed, and a File with no readable text are all absent. The coverage count does not include them.
• The meaning data. Search by meaning reads only versions that have their data. With none ready, it returns nothing, and a hybrid search falls back to exact words.
• The filters. A tag, a File id, a collection id or a media type narrows the search. A narrow filter can leave nothing.
• Your access. A credential limited to a View searches only the Files in the View. The rest read as missing.
• The catalog. Passages and entities have separate searches. A passage search never returns an entity.

​

What Penumbra does

By itself:

• Searches the current version of each live File that is ready. It skips Files in the trash, Files still processing, Files that failed and Files with no readable text.
• In exact-word mode, needs every plain word of the query to match. It accepts a phrase in double quotation marks, the word or, and a minus sign before a word to exclude it.
• Searches by meaning only the versions whose data is ready, and reports the coverage as partial or none with a warning.
• Prints the mode you asked for, the mode it used and the coverage with every result of penumbra files search.
• Limits a credential that is bound to a View with Files or collections to the Files in the View.
• Searches passages by default in hybrid mode. Entity search through penumbra graph search uses exact words by default.
• MCP: omnisearch leaves out weak matches by meaning and says so. penumbra files search applies no such cut.

You must:

• Read the mode and the coverage before you decide that nothing matches.
• Try the query again as exact words, with fewer words, as a phrase or with or.
• Check the state of the File and your own access.
• Tell the person which cause applied, or which causes you could not exclude.

Not handled:

• The coverage count ignores versions that are still processing, so a full count does not prove that the search covered every File.

​

Do

1. Run the search and read its first line: penumbra files search "<query>". Note the mode and the coverage. If the hint says that no File has searchable text yet, run penumbra files list and read the status of each File (problem new-file-not-searchable-yet).
2. Remove the filters that you passed: --tag, --file-id, --collection-id, --filter-media-type and --source. The hint names the filters you used.
3. Search by exact words with fewer words: penumbra files search "renewal" --mode lexical. For a phrase, put it in double quotation marks inside the query. For alternatives, use or.
4. Search by meaning and words together: penumbra files search "<query>" --mode hybrid. If the coverage is partial or none, only some versions are searchable by meaning. Exact words cover the rest. MCP: call omnisearch again in lexical mode, with fewer words.
5. Check the File: penumbra files find "<name>", then penumbra files inspect <file>. The processing: line shows the lexical state and the semantic state. Run penumbra files list --trashed to see whether someone trashed the File. If the text is empty or garbled, run penumbra files text <file> (recipe check-file-text).
6. Check what you can see: penumbra access me. If a View limits you, items outside the View look absent, and counts cover the View only (problem hidden-reads-as-missing).
7. Search the entities too: penumbra graph search "<query>" --mode hybrid. penumbra search "<query>" searches passages and entities in one call.
8. Report the result with its limits. Say what you searched, the mode, the coverage, and what you could not see.

​

Don’t

• Don’t tell the person that a fact is not in the project after one empty search. The File may be processing, outside your View, or not matched by your words.
• Don’t read a full coverage count as proof that the search covered every File. The count leaves out a File that is still processing.
• Don’t search by meaning only (--mode semantic) while the coverage is partial or none. That mode skips the versions without data and can return nothing.
• Don’t upload the File again. The same bytes give the same File and change nothing (problem same-bytes-no-new-version).

​

Check

• The query returns a passage with its File id, version id and passage id: penumbra search "<query>" prints them on a cite: line.
• Or you can name the cause: the words, the File state, the data for meaning, a filter, or your View. The person has heard it.

​

Related

Card search, with rule search.2. Card file. Problems new-file-not-searchable-yet and hidden-reads-as-missing. Recipes check-file-text and answer-with-citations.

​

Keep going

Search · File · Passage and citation · A new File is not searchable yet · Something outside the View reads as not found