From 2aefa28b56f6ac2c1fbec66c0aea653d5ad3b4c7 Mon Sep 17 00:00:00 2001 From: August Cayzer Date: Mon, 26 Oct 2026 15:42:00 +0000 Subject: [PATCH] docs(build): say that search finds a file by its extracted text --- content/docs/build/handle-files.mdx | 17 +++++++++++++++++ content/docs/build/list-filter-search.mdx | 2 ++ content/docs/catalog/items.mdx | 2 +- 3 files changed, 20 insertions(+), 1 deletion(-) diff --git a/content/docs/build/handle-files.mdx b/content/docs/build/handle-files.mdx index 9cb90865..503ebfb0 100644 --- a/content/docs/build/handle-files.mdx +++ b/content/docs/build/handle-files.mdx @@ -104,6 +104,23 @@ A write that names another hash in `blob_ref`, such as one copied from elsewhere A hash in any other property, such as an image link in a note's body, is text: the write is taken and the hash lends nothing. +## Find a file by its text + +Once the housekeeping job has written a file item's `extracted_text`, [search](/build/list-filter-search#search) finds the file by any word in it: + +```bash tab="CLI" tab-group="client" +marfa search quokka --type core.file +``` + +```http tab="HTTP" +GET /search?q=quokka&type=core.file +Authorization: Bearer +``` + +The job runs every 30 seconds by default, so a new file is found by its `title`, `description` and tags first and by its text a little later. Search matches only the text the job kept, which [`MARFA_ENRICHMENT_MAX_TEXT_CHARS`](/run/settings) limits. A file in the bin is never found. A device that holds the file finds it by its text once it has fetched the item with its `extracted_text`, which it does when it next catches up. + +Enrichment is on unless the [settings](/run/settings) switch it off, and an image has text only while OCR is on. + ## Download the bytes [Download a blob](/api-reference/blobs/downloadBlob) answers the bytes as they were uploaded: diff --git a/content/docs/build/list-filter-search.mdx b/content/docs/build/list-filter-search.mdx index 8856d5a7..0b2034cd 100644 --- a/content/docs/build/list-filter-search.mdx +++ b/content/docs/build/list-filter-search.mdx @@ -173,6 +173,8 @@ Each entry in `data` holds the `item`, its `metadata`, a `relevance_score`, and Put a query in double quotes to match a phrase. A search takes a listing's parameters too, such as `type`, `tags` and `filter`. +Search also reads the text of a file. After the `enrichment-sweep` job has read a file item's bytes and written its `extracted_text`, a search finds the file by any word in that text, as it finds any other `string` field, on the server and in a copy on a device. Until then, a search finds the file only by its other fields and tags. See [Handle files](/build/handle-files#find-a-file-by-its-text). + ## Count items [Get item counts](/api-reference/items/getItemStats) counts the items a listing would match, by state or, with `by=type`, by type: diff --git a/content/docs/catalog/items.mdx b/content/docs/catalog/items.mdx index dba56ac1..79ece315 100644 --- a/content/docs/catalog/items.mdx +++ b/content/docs/catalog/items.mdx @@ -13,4 +13,4 @@ Search always reads these fields where they hold a `string` ([`search-and-filter src/generated/catalog/searched-field-names.md -It also reads every other `string` field a type declares or inherits, unless the field sets `searchable` to `false`, and an item's tags. [List, filter and search](/build/list-filter-search#search) shows how to search. +It also reads every other `string` field a type declares or inherits, unless the field sets `searchable` to `false`, and an item's tags. That includes a file item's `extracted_text`, the text Marfa reads from the file's bytes. A type that inherits a file type can't set `searchable` to `false` on it. [List, filter and search](/build/list-filter-search#search) shows how to search.