Skip to main content

searchFileContent

Public search across the content of files attached to records.

Description​

This method searches inside the text of files attached to your records - PDFs, documents and the like - and returns the files that match, each with the fragment where the match was found. It returns a Promise that resolves to an IFileSearchResponse object.

FileUploading.searchFileContent(query, langCode, extensions, ownerTables, localeCodes, onlyTruncated, offset, limit);

Parameters​

query: string
Search query. At least 3 characters - a shorter one is rejected with 400.
example: "transportation"

langCode: string (optional)
Language of the query. Default: "en_US".
example: "en_US"

extensions: string[] (optional)
Filter by file extension.
example: ["pdf", "docx"]

ownerTables: string[] (optional)
Filter by the section the attached record belongs to.
example: ["products", "pages"]

localeCodes: string[] (optional)
Filter by the locale of the link, not of the file content.
example: ["en_US"]

onlyTruncated: boolean (optional)
Return only files whose extracted text was cut at the size ceiling.
example: true

offset: number (optional)
Parameter for pagination. Default: 0.
example: 0

limit: number (optional)
Parameter for pagination. Default: 10, maximum 50 - a larger value is rejected with 400.
example: 10

💡 Two things to know before you render the result​

The unit is a file, not a fragment. One snippet per file, even when the document matches on twenty pages. snippet.pageFrom says which page the fragment starts on.

The match is marked with control characters, not HTML. Inside snippet.text every match is wrapped in U+0002 and U+0003. Paste it into your markup unchanged and the reader sees nothing - replace them with your own highlighting:

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

🔒 What the search returns​

Only files of visible records, and only in the sections enabled in your project settings. Personal sections are narrowed to the caller's own records, and the admins section is never returned. A 403 with a tariff message means the feature is not 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": 124,
  "offset": 0,
  "limit": 10,
  "queryLanguage": {
    "resolved": ["english"],
    "source": "explicit",
    "candidates": ["english"]
  },
  "warnings": [],
  "items": [
    {
      "id": 1077,
      "storageKey": "files/project/file/644/product/db1918c4.pdf",
      "extension": "pdf",
      "title": null,
      "langCode": "en",
      "pageCount": 244,
      "rank": 0.0971,
      "snippet": {
        "text": "Active Transportation Demand Management",
        "pageFrom": 86
      },
      "owners": [
        {
          "tableName": "products",
          "dataId": 644,
          "title": "COG - March 17, 2016",
          "langCode": "en_US"
        }
      ],
      "ownersTotal": 2
    }
  ]
}

Response schema​

Schema: IFileSearchResponse

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

offset: number
Offset the page starts at.
example: 0

limit: number
Page size.
example: 10

queryLanguage: IFileSearchQueryLanguage
How the query language was resolved: resolved, source, candidates.
example: { "resolved": ["english"], "source": "explicit", "candidates": ["english"] }

warnings: string[]
Warnings about the search, empty when there are none.
example: []

items: IFileSearchItem[]
The found files.
example: [{ "id": 1077, "extension": "pdf" }]

items[].id: number
Identifier 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: null

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; results are sorted by it descending.
example: 0.0971

items[].snippet: IFileSearchSnippet | null
The matching fragment: text plus the page it starts on.
example: { "text": "Active Transportation", "pageFrom": 86 }

items[].owners: IFileSearchOwner[]
Records the file is attached to, one entry per locale.
example: [{ "tableName": "products", "dataId": 644 }]

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