Search with the Querytext Parameter

You can use the querytext parameter of the Search Folders or Files APIs in the REST API for Documents to take advantage of string search, tag search, and custom metadata field search at the same time.

The querytext search string is available in the Search Folders or Files and the Search Folders or Files Under Specific Folder ID endpoints, to match folder or file names and allow for tag search or custom metadata field search as well. You can use querytext to search an entire directory tree in your home (self) directory as well as shared folders.

To set up querytext searches with the REST APIs:

  1. Create files and folders, and add tags to them for string searches.

    Tags currently support only CONTAINS.

    1. Plan where you will place each tag because tags are inherited from parent folders.

    2. Set tags, add tags, or remove tags with the following APIs: Set Folder Tags, Edit Folder Tags, Set File Tags, and Edit File Tags

  2. Add metadata collections.

    1. As an administrator, create global collections (personal collections are not supported as indexed collections).

    2. Determine which fields you will need to support the search, and call APIs in the metadata resource to index those fields.

      There is a limit of 100 fields to be indexed. You cannot remove fields from the index. The search is done on Favorite shared folders first and then other shared folders, up to 100. You may want to designate some folders as Favorites before searching, to ensure better search results.

    3. Metadata fields of an integer type cannot be searched as a number.

    4. You can search metadata fields of a Date type in a search API from the REST API for Documents. This enables you to search for exact date matches or for a range of dates (that is, files where the date falls between a specific start date and a specific end date).

  3. Build your query.

    1. Use a search strings in the querytext parameter of the Search Folders or Files and the Search Folders or Files Under Specific Folder ID endpoints to search your folder and file names, tags, and indexed metadata fields.

      For examples of tags and custom metadata searches, see the descriptions of the endpoints in the REST API for Documents.

    2. Search queries require URL encoding of the single-quotation-mark character ( ') into %60. For example, Collection1.field1<CONTAINS>'myValue' turns into Collection1.field1<CONTAINS>%60myValue%60.

    3. Start with simple queries to validate that your conditions do indeed find results.

    4. You can build more complex queries by combining parentheses, <AND> clauses, and <OR> clauses.