About Search

About Search

Contents

GET /search API supports the following parameters that define how the search is performed and how the search results are returned:

  • query
  • sort
  • start
  • count

SEE ALSO:
- Lucene search

Query Parameter

The query parameter contains the term to be searched. It supports a number of query fields that allow you to restrict the search to particular parts of a fie or folder’s metadata or to specific files or folders.

The query parameter is based on Lucene search query syntax which takes the following format:

query=field:value AND field:value AND field:value

For example, to search for all files called foobar, use the query parameter with the following value:

file:true AND name:foobar

Note the following: - The search value must be at least three characters. - The search value can only search for words that begin with three or more characters. For example, searching for man matches manual but not postman. - The search value is not case-sensitive. - The entire search query must be URL encoded and any special characters escaped.

Escaping and Encoding Search Queries

The characters contained in the value of the query parameter must be escaped:

  1. Escape the following special characters by adding a backlash before the character, as described in the Lucene documentation: + _ && || ! () {} [] ^ " ~ * ? : \ .
  2. URL-encode the entire search query to make it URL-safe.

NOTES:
1. Make sure to escape any whitespace if you want words to be treated as part of a phrase. Otherwise, Lucene treats the space as a query separator. 2. You can substitute + or %20 for spaces.

EXAMPLE:

To search for the track Ace of Spades by Motorhead, you should:

  1. Lucene-escape the whitespace in the song title in order to search for the entire phrase:
    Ace\ of\ Spades
  2. Prepare the search query:
    title:Ace\ of\ Spaces AND artist:Motorhead
  3. URL-encode the entire query:
    title%3AAce%5C%20of%5C%20Spades%20AND%20artist%3AMot%F6rhead

Searching for Files and Folders Only

By default the search API returns both folders and files that meet the search criteria. To search for files only, include the following in your query:

file:true

To search for folders only, set the file query field to false:

file:false

Searching for Files by Name

Consider a folder containing the following files:

  • foo.txt
  • bar.txt
  • foobar.txt
  • FooBar.txt
  • foobar.jpg
  • barfoo.txt
  1. The search result of a query parameter set to name:foo returns these results:

    • foo.txt
    • foobar.txt
    • FooBar.txt
    • foobar.jpg
  2. The search result of a query parameter set to name:bar returns the following results. Note, that FooBar.txt is matched because its uppercase “B” causes the search algorithm to treat bar as a new word. The files foobar.txt and foobar.jpg are not matched even though they contain the word bar. Matches only happen from the start words.

    • barfoo.txt
    • FooBar.txt
    • bar.txt
  3. The search result of a query parameter set to name:foobar returns these results:

    • foobar.txt
    • foobar.jpg
    • FooBar.txt

Searching File Types

You can use the following query to search for all MPEG files named movie:

contentType:video/mpeg AND name:movie

Searching for the Total Number of Artists

The following query returns the total number of artists across all folders:

artist:*

Searching by File Type

Use this query to search for all GIF files across all folders:

contentType:image/gif

Searching by Geolocation

You can use the following query syntax to search for a file containing specific geolocation coordinates:

geoLatitude:[53.3439 TO 53.3440] AND geoLongitude:[\-6.2672 TO \-6.2671]

You can also choose to use a fully encoded query:

geoLatitude%3A%5B53.3439+TO+53.3440%5D+AND+geoLongitude%3A%5B%5C-6.2672+TO+%5C-6.2671%5D

Wildcard Searches

You can use wildcard at the end or in the middle of the search query. Search queries where a wildcard appears at the start of the query are not supported.

Searching for All Files and Folder in a Directory

To search for all files in the root directory and child directories, use this query:
path:*

Searching for All Audio Files

To search for audio files of all audio types, use this query:
contentType:audio/*

Sort Parameter

The sort parameter allows you to control the sort order in which the search response is returned. You can define any number of sort orders. The items are initially sorted using the first sort order. When the same value is discovered more than once, the second sort order is followed. The process completes when all sort orders are checked.

Sort order can be:

  • ascending - when you specify asc
  • descending - when you specify desc

To override the default sorting behavior, use the sort parameter with the following syntax:

sort={field}+(asc|desc)

EXAMPLES:

  • This request retrieves the metadata for the /media folder. The folders and files are sorted by filename and listed in descending order.
GET /user/{userUid}/repository/{repository}/folder?path=%Fmedia&sort=name+desc
  • This request sorts files or folders in a ascending order, first by extension and then by name:
sort=extension+asc,name+asc

NOTE:

Some files may not have all of the metadata parameters specified. When you sort by a parameter that is missing for some of the files, the files that do have the parameter specified will be sorted by that parameter. The remaining files will appear either at the top or the bottom of the list and will be sorted in descending or ascendng order (if specified).

For example, if you specify:

  • ?sort=CreationDate+desc - The files that have creationDate will appear at the top of the list and will be sorted first by the creation date and then by descending order. The files without creationDate will appear at the bottom of the list in descending order.
  • ?sort=CreationDate+asc - The files that do not have creationDate will appear at the top of te list in ascending order. The files that have creationDate will appear at the bottom of the list and will be sorted first by the creationDate and then by ascending order.

Start Parameter

You can use the start parameter to specify which of the pages should be returned in the response. The default page is page 1.

Count Parameter

The count parameter limits the number of items per page. The result is splitting of the list across a number of pages required to display all of the information.

Searchable Fields and System Attributes

The following tables list the supported query fields and system attributes. If you do not specify the query field in the query, the text is matched against all available fields by default.

You can also use these fields to modify the sort order of the search request.

SEARCHABLE FIELDS

Search Field Sort Order
name sort by file name
type sort either by file or folder
versionCreated sort by the creation date of the file version
size sort by file size
extension sort on a file extension, such as .mp3 or .flv
path sort by a file path
file sort by file attribute (true for files, false for folders; false is less than true in sort order

SEARCHABLE SYSTEM ATTRIBUTES

Search Field System Attribute
album Album
artist Artist
captureDate Capture-Date
compilation Compilation
contentType Mime-Type
creationDate Creation-Date
extension Extension
favorite Favorite
genre Genre
height Height
modificationDate Modification-Date
priority Priority
source Source
tags Tags
title Title
timelineDate Timeline-Date
track Track
width Track
year Year

Search Examples

You can use the following examples in your code. Make sure that the query string is URL encoded.

Example 1. Searching for Folders

This search query results in a list of all folders.

search?query=file:false

Example 2. Searching for Files

This search query results in a list of all files.

search?query=file:true

Example 3. Searching for Files with a Specific Extension

This search query results in a list of all files with .jpg extension.

search?query=extension:jpg

Example 4. Searching for Files or Folders of Specific Size

This search query results in a list of all files and folders that are 1611234 in size.

Search?query=size:1611234

Example 5. Example of Search with Start and Count Parameters

This search query results in a list of all files. The files are displayed starting with page 1 with 5 files per page. The files are split across as many pages as necessary.

search?query=file:true&start=1&count=5

Example 6. Example of Search with Start, Count, and Sort Parameters

This search query results in a list of all files. The files are displayed starting with page 1 with 8 files per page. The files are sorted in a descending order.

search?query=file:true&start=1&count=8&sort=size+desc

Example 7. Example of Search with Start, Count, and Sort Parameters

This search query results in a list of all files. The files are displayed starting with page 1 with 8 files per page. The files are sorted by size and displayed in ascending order.

search?query=file:true&start=1&count=8&sort=size+asc

Example 8. Searching for Audio Files

This search query results in a list of all audio files.

search?query=file:true AND contentType:audio/*

Example 9. Searching for File by File Name

This search query results in a file named ElindaArambavo.mp3, if such file exists.

search?query=name:ElindaArambavo.mp3

Example 10. Searching for Files or Folders Created in a Specified Date Range

This search query results in a list of all files and folders created between 2015-10-14 at 01:21:06.00 and 2015-12-13 at 19:45:52.18.

Search?query=versionCreated:[2015-10-14T01:21:06.009Z TO 2015-12-13T19:45:52.186Z]

Example 11. Searching for Files or Folders within Specified Size Range

This search query results in a list of all files and folders within the size range from 9078 to 209876.

search?query=size:[9078 TO 209876]

Example 12. Searching by System Attribute - Artist

This search query results in a list of files and folders where the artist is Shankar Mahadevan.

search?query=artist:*Shankar Mahadevan*

Example 13. Searching by Genre

This search query results in a list of all files and folders with genre www.123musiq.com.

search?query=genre:www.123musiq.com*

Example 14. Complex Search Example

This search query results in a list of all files and folders that were created between 2015-10-10 at 01:21:06.00 and 2015-12-13 at 19:45:52.18 AND meet ONE of the following criteria:

  • genre is www.123musiq.com
  • name Mahadevan.mp3
  • artist is Shankar Mahadevan
search?query=(genre:www.123musiq.com* OR name:Mahadevan.mp3 OR artist:*Shankar Mahadevan*) AND versionCreated:[2015-10-10T01:21:06.009Z TO 2015-12-13T19:45:52.186Z]

Copyright © 2015-2017, Verizon and/or its Licensors. All rights reserved.