searchFileContent

Search the text of files attached to records. No authorization is required.

Description

Searches the text of files attached to your records (PDFs, documents and the like). Resolves to an IFileSearchResponse with the matching files, each with the fragment where the match was found.

.searchFileContent(

, , , , , , ,

);

Parameters schema

Schema

query(required): string
Search query, at least 3 characters — shorter is rejected with 400.
example: "transportation"

langCode: string
Language of the query. Default: the langCode passed to defineOneEntry ("en_US" if none). A code the search doesn't support (for example "xx_YY") is rejected with 400 "Unknown text search language".
example: "en_US"

extensions: string[]
Filter by file extension, sent comma-separated.
example:

[
  "pdf",
  "docx"
]

ownerTables: string[]
Filter by the section the attached record belongs to, sent comma-separated.
example:

[
  "products",
  "pages"
]

localeCodes: string[]
Filter by the locale of the link, not of the file content.
example:

[
  "en_US"
]

onlyTruncated: boolean
Return only files whose extracted text was cut at the size ceiling.

offset: number
Number of records to skip. Default: 0. offset + limit must not exceed 200; a larger window is rejected with 400.
example: 0

limit: number
Number of files to return. Default: 10, maximum 50; a larger value is rejected with 400. offset + limit must not exceed 200.
example: 10

The SDK always sends langCode, so by default the query is searched in your app's language and queryLanguage.source is "explicit". A query in a different script isn't detected automatically: a Cyrillic query with the default en_US is still searched as English. To let the API choose the language from the query and the project settings, pass an empty string as langCode.

Before you render the result

The unit is a file, not a fragment. You get one snippet per file, even when the document matches on twenty pages. snippet.pageFrom tells you which page the fragment starts on.

Matches are marked with control characters, not HTML. Inside snippet.text, every match is wrapped in U+0002 and U+0003. If you insert the text into your markup unchanged, the reader won't see the highlighting, so replace them with your own. The text comes from the file itself, so escape it first and add the tags after:

const escapeHtml = (text) =>
  text
    .replaceAll('&', '&')
    .replaceAll('<', '&lt;')
    .replaceAll('>', '&gt;')
    .replaceAll('"', '&quot;');

const html = escapeHtml(item.snippet?.text ?? '')
  .replaceAll('\u0002', '<mark>')
  .replaceAll('\u0003', '</mark>');

What the search returns

The search returns only files of visible records, and only in the sections enabled in your project settings. Personal sections are limited to the caller's own records, and the admins section is never returned. A 403 response means file search isn't included in your plan.

Examples

Minimal example

const response = await FileUploading.searchFileContent('transportation');

Only PDFs attached to products

const response = await FileUploading.searchFileContent(
  'transportation',
  'en_US',
  ['pdf'],
  ['products'],
);

Second page

const response = await FileUploading.searchFileContent(
  'transportation',
  'en_US',
  undefined,
  undefined,
  undefined,
  undefined,
  10,
  10,
);

Example response

{
  "total": 0,
  "offset": 0,
  "limit": 10,
  "queryLanguage": {
    "resolved": [
      "english"
    ],
    "source": "explicit",
    "candidates": [
      "english"
    ]
  },
  "warnings": [
    "processing_disabled"
  ],
  "items": []
}

Response schema

Schema: IFileSearchResponse

total: number
Total number of matching files.
example: 166

offset: number
Number of records to skip.
example: 0

limit: number
Maximum number of records to return.
example: 10

queryLanguage: IFileSearchQueryLanguage
How the query language was resolved.

queryLanguage.resolved: string[]
Text-search configurations the query ran with, for example english.
example: ["english"]

queryLanguage.source: string
How the language was chosen: explicit (from langCode), or script, facet, configured or fallback when langCode is empty.
example: "explicit"

queryLanguage.candidates: string[]
Languages that were considered.
example: ["english"]

warnings: string[]
Reasons the result may be empty or approximate: processing_disabled, query_too_common, query_language_capped, semantic_unavailable, fuzzy_fallback. Empty when there are none.

items: IFileSearchItem[]
Files that match the query.

items.id: number
ID of the indexed file.
example: 1077

items.storageKey: string
Key of the object in the storage; the file link is built from it.
example: "files/project/file/644/product/db1918c4.pdf"

items.extension: string
File extension.
example: "pdf"

items.title: string | null
Title from the document metadata, null when the document carries none.
example: "Microsoft Word - COG Agenda.docx"

items.langCode: string | null
Language of the file content, detected on indexing.
example: "en"

items.pageCount: number | null
Number of pages, for paged formats.
example: 244

items.rank: number
Relevance of the match; the API sorts by it descending.
example: 0.0971

items.snippet: IFileSearchSnippet | null
The matching fragment.

items.owners: IFileSearchOwner[]
Records the file is attached to, limited to those the caller may see.

items.ownersTotal: number
How many records visible to the caller reference the file.
example: 2

---