Search Resource Endpoints

The Search resource endpoints allow REST clients to perform queries on the Nuxeo repository, save these queries and reproduce them later on.

Endpoints

There are three search endpoints:

page provider (pp)
query (lang) - not to be confused with the deprecated query endpoint
saved search (saved)

Path	Description
GET `/api/v1/search/lang/{queryLanguage}/execute`	Executes a query in a given query language. Default language is NXQL.
POST `/api/v1/search/lang/{queryLanguage}/bulk/{actionId}`	Executes a bulk action on a query in a given query language. Default language is NXQL.
GET `/api/v1/search/pp/{providerName}/execute`	Executes a search using a specific page provider.
POST `/api/v1/search/pp/{providerName}/bulk/{actionId}`	Executes a bulk action using a specific page provider.
GET `/api/v1/search/pp/{providerName}`	Gets the definition of a given page provider.
GET `/api/v1/search/saved`	Gets a list of saved searches.
POST `/api/v1/search/saved`	Saves a search.
GET `/api/v1/search/saved/{searchId}`	Retrieves a saved search.
PUT `/api/v1/search/saved/{searchId}`	Updates a saved search.
DELETE `/api/v1/search/saved/{searchId}`	Deletes a saved search.
GET `/api/v1/search/saved/{searchId}/execute`	Executes a saved search.
GET `/api/v1/search/saved/{searchId}/bulk/{actionId}`	Executes bulk action on a saved search.

Execution Parameters

Searches can be parameterized with execution parameters which can be passed to all /search/**/execute endpoints.

Key	Type	Description	Default Value / Example
`query`	string	The query to perform	`SELECT * FROM Document`
`pageSize`	integer	Number of entries per page	0 (no pagination) The maximum is 1000 by default. See the related page on the Explorer in order to customize it.
`currentPageIndex`	integer	Selected page index	0
`maxResults`	integer	Maximum entries	200
`sortBy`	string	Property sorting	Example: `sortBy="dc:title,dc:description"`
`sortOrder`	string	Sort order	Examples: `sortOrder="DESC"` or `sortOrder="ASC"`
`offset`	number	Current page offset.	0
`highlight`	string	List of fields to highlight.	Example: `highlight="dc:title.fulltext,dc:description.fulltext"`. Check Elasticsearch Highlights for more details.
`queryParams`	string	Ordered parameters	Example: For a query pattern like `Select * From Document where dc:title = ?`, the `queryParams` value should be "My Title". This is only useful when using a page provider, defined server-side.
`parameter1`, `parameter2`...	string	Named parameters	Example: For a query pattern like `Select * From Document where dc:title = :title1`, the `title1` parameter should be "My Title". Parameter names should be strictly different from property names (and other query parameters). This is only useful when using a page provider, defined server-side.

Saved Search Properties

Saved searches are composed of the following properties:

Property	Type	Description
`queryParams`	string	Ordered query parameters
`namedParams`	object	Named parameters
`query`	string	Query to be executed, mutually exclusive with `providerName`
`queryLanguage`	string	Query language, mutually exclusive with `providerName` (default is NXQL)
`providerName`	string	Page provider to use in the search, mutually exclusive with `query` and `queryLanguage`
`contentViewData`	string	JSON object containing content view related data

These properties are particularly relevant for creating and updating saved searches. Search execution parameters can be stored as properties of the saved search, which will be used when the search is executed. These parameters can be overridden if passed again with new values to the execution endpoint.

Examples and Sample Code

Searching by Query

Requests

GET http://NUXEO_SERVER/nuxeo/api/v1/search/lang/NXQL/execute?query=select * from Document

GET http://NUXEO_SERVER/nuxeo/api/v1/search/lang/NXQL/execute?query=select * from Document&pageSize=2&currentPageIndex=1

Response

{
    "entity-type": "documents",
    "isPaginable": true,
    "resultsCount": 39,
    "pageSize": 2,
    "maxPageSize": 100,
    "currentPageSize": 2,
    "currentPageIndex": 1,
    "numberOfPages": 20,
    "isPreviousPageAvailable": true,
    "isNextPageAvailable": true,
    "isLastPageAvailable": true,
    "isSortable": true,
    "hasError": false,
    "errorMessage": null,
    "totalSize": 39,
    "pageIndex": 1,
    "pageCount": 20,
    "entries": [
        {
            "entity-type": "document",
            "repository": "default",
            "uid": "6a2707d7-1340-4f7c-935b-6f01f0c1bf15",
            "path": "/management/administrative-infos/Mac OS X--44d452c00edf0bf0f86447b1f40923d6-79d535faa48b39f3f358fe5dad3c503b--org.nuxeo.ecm.smtp",
            "type": "AdministrativeStatus",
            "state": "undefined",
            "versionLabel": "",
            "isCheckedOut": true,
            "title": "Mac OS X--44d452c00edf0bf0f86447b1f40923d6-79d535faa48b39f3f358fe5dad3c503b--org.nuxeo.ecm.smtp",
            "lastModified": "2014-09-04T09:51:15.46Z",
            "facets": [
                "HiddenInNavigation"
            ],
            "changeToken": "1409824275462",
            "contextParameters": {
                "documentURL": "/nuxeo/nxdoc/default/6a2707d7-1340-4f7c-935b-6f01f0c1bf15"
            }
        },
        {
            "entity-type": "document",
            "repository": "default",
            "uid": "5366b1e4-10f3-4ab6-9510-c31e1e5faea9",
            "path": "/management/administrative-infos",
            "type": "AdministrativeStatusContainer",
            "state": "undefined",
            "versionLabel": "",
            "isCheckedOut": true,
            "title": "administrative-infos",
            "lastModified": "2014-09-04T09:51:15.44Z",
            "facets": [
                "Folderish",
                "HiddenInNavigation"
            ],
            "changeToken": "1409824275441",
            "contextParameters": {
                "documentURL": "/nuxeo/nxdoc/default/5366b1e4-10f3-4ab6-9510-c31e1e5faea9"
            }
        }
    ]
}

Querying with Elasticsearch

In order to perform NXQL queries on Elasticsearch repository through the search endpoints, the following configuration must be added to $NUXEO_HOME/bin/nuxeo.conf:

elasticsearch.override.pageproviders=default_search,REST_API_SEARCH_ADAPTER

Note that default_search is the only page provider querying on Elasticsearch by default. When defining elasticsearch.override.pageproviders conf property, don't forget to add it or else it won't query Elasticsearch anymore. See also HOWTO: Make a Page Provider or Content View Query Elasticsearch Index.

Searching by Page Provider

Using page providers defined server-side instead of redefining the query on client side might also be useful for better reusability.

Here are different use cases for defining page providers and making it possible to pass parameters from the client.

Without Parameters

<coreQueryPageProvider name="latest_docs">
  <pattern>
    SELECT * FROM Document WHERE ecm:mixinType != 'HiddenInNavigation'
    AND ecm:isVersion = 0 AND ecm:isTrashed = 0
  </pattern>
  <sort column="dc:modified" ascending="false" />
  <pageSize>50</pageSize>
</coreQueryPageProvider>

Example Request

GET http://NUXEO_SERVER/nuxeo/api/v1/search/pp/latest_docs/execute

Parameters Referenced with the '?' Character

<coreQueryPageProvider name="tree_children">
  <pattern>
    SELECT * FROM Document WHERE ecm:parentId = ? AND ecm:isProxy = 0
    AND ecm:mixinType = 'Folderish' AND ecm:mixinType != 'HiddenInNavigation'
    AND ecm:isVersion = 0 AND ecm:isTrashed = 0
  </pattern>
  <sort column="dc:title" ascending="true" />
  <pageSize>50</pageSize>
</coreQueryPageProvider>

Example

GET http://NUXEO_SERVER/nuxeo/api/v1/search/pp/tree_children/execute?queryParams=47dd6d8d-d8d0-4a09-9e3e-e30fc8877df1

Named Parameter in the Pattern

<coreQueryPageProvider name="docs_by_title_and_desc">
  <pattern>
    SELECT * FROM Document WHERE dc:title = :title AND dc:description LIKE :desc
  </pattern>
  <sort column="dc:title" ascending="true" />
  <pageSize>50</pageSize>
</coreQueryPageProvider>

Example

GET http://NUXEO_SERVER/nuxeo/api/v1/search/pp/docs_by_title_and_desc/execute?title=mytitle&desc=mydesc

Named Parameter in WHERE Clause

<coreQueryPageProvider name="docs_by_title_if_any">
  <whereClause>
    <predicate parameter="dc:title" operator="=">
      <field name="title" />
    </predicate>
  </whereClause>
  <sort column="dc:title" ascending="true" />
  <pageSize>50</pageSize>
</coreQueryPageProvider>

Example

GET http://NUXEO_SERVER/nuxeo/api/v1/search/pp/docs_by_title_if_any/execute?title=mytitle

GET http://NUXEO_SERVER/nuxeo/api/v1/search/pp/docs_by_title_if_any/execute

In the second example, no filtering is performed: the title parameter is not provided so the corresponding predicate is not part of the resulting query.

By default, named parameters are treated as String values. If you need further configuration, define a document type and the associated schema so that conversions are accurate for numbers, dates, booleans, etc.

Named Parameter in WHERE Clause and Typing

Assuming a document type NamedParamDoc and the associated schema prefixed np have been defined, the following query can be performed:

<coreQueryPageProvider name="docs_by_title_complex">
  <searchDocumentType>NamedParamDoc</searchDocumentType>
  <whereClause>
    <predicate parameter="dc:title" operator="=">
      <field name="np:title" />
    </predicate>
    <predicate parameter="ecm:isVersion" operator="=">
      <field xpath="np:isCheckedIn" />
    </predicate>
  </whereClause>
  <sort column="dc:title" ascending="true" />
  <pageSize>50</pageSize>
</coreQueryPageProvider>

Example

GET http://NUXEO_SERVER/nuxeo/api/v1/search/pp/docs_by_title_complex/execute?np%3Atitle=mytitle&np%3AisCheckedIn=true

Response

{
    "entity-type": "documents",
    "isPaginable": true,
    "resultsCount": 1,
    "pageSize": 50,
    "maxPageSize": 100,
    "currentPageSize": 1,
    "currentPageIndex": 0,
    "numberOfPages": 1,
    "isPreviousPageAvailable": false,
    "isNextPageAvailable": false,
    "isLastPageAvailable": false,
    "isSortable": true,
    "hasError": false,
    "errorMessage": null,
    "totalSize": 1,
    "pageIndex": 0,
    "pageCount": 1,
    "entries": [
        {
            "entity-type": "document",
            "repository": "default",
            "uid": "1c5fcfa7-3cd1-446e-b3d3-5f8c41d61ea7",
            "path": "/default-domain/UserWorkspaces/Administrator",
            "type": "Workspace",
            "state": "project",
            "versionLabel": "",
            "isCheckedOut": true,
            "title": "Administrator",
            "lastModified": "2014-09-04T09:52:15.83Z",
            "facets": [
                "Folderish",
                "SuperSpace"
            ],
            "changeToken": "1409824335836",
            "contextParameters": {
                "documentURL": "/nuxeo/nxdoc/default/1c5fcfa7-3cd1-446e-b3d3-5f8c41d61ea7/view_documents"
            }
        }
    ]
}

With Elasticsearch

Default Page provider in Nuxeo Server

<genericPageProvider name="aggregates_1"
  class="org.nuxeo.elasticsearch.provider.ElasticSearchNxqlPageProvider">
  <property name="coreSession">#{documentManager}</property>
  <property name="maxResults">-1</property>
  <pageSize>20</pageSize>
  <fixedPart>SELECT * FROM Document</fixedPart>
  <aggregates>
    <aggregate id="source" type="terms" parameter="dc:source">
      <field schema="advanced_search" name="source_agg" />
      <properties>
        <property name="size">5</property>
      </properties>
    </aggregate>
    <aggregate id="coverage" type="terms" parameter="dc:coverage">
      <field schema="advanced_search" name="coverage_agg" />
      <properties>
        <property name="size">5</property>
      </properties>
    </aggregate>
    <aggregate id="nature" type="terms" parameter="dc:nature">
      <field schema="advanced_search" name="nature_agg" />
      <properties>
        <property name="size">5</property>
      </properties>
    </aggregate>
  </aggregates>
</genericPageProvider>

Examples

GET http://NUXEO_SERVER/nuxeo/api/v1/search/pp/aggregates_1/execute

Response

{
  "entity-type": "documents",
  "isPaginable": true,
  "resultsCount": 16,
  "pageSize": 20,
  "maxPageSize": 1000,
  "currentPageSize": 15,
  "currentPageIndex": 0,
  "numberOfPages": 1,
  "isPreviousPageAvailable": false,
  "isNextPageAvailable": false,
  "isLastPageAvailable": false,
  "isSortable": true,
  "hasError": false,
  "errorMessage": null,
  "totalSize": 16,
  "pageIndex": 0,
  "pageCount": 1,
  "entries": [
    {
      "entity-type": "document",
      "repository": "test",
      "uid": "48706617-f28f-4fd5-9a7c-1b7759908eb9",
      "path": "/folder_2",
      "type": "Folder",
      "state": "project",
      "versionLabel": "",
      "isCheckedOut": true,
      "title": "Folder 2",
      "lastModified": "2014-09-18T13:42:16.31Z",
      "properties": {
        "dc:description": null,
        "dc:language": null,
        "dc:coverage": null,
        "dc:valid": null,
        "dc:creator": "Administrator",
        "dc:modified": "2014-09-18T13:42:16.31Z",
        "dc:lastContributor": "Administrator",
        "dc:format": null,
        "dc:expired": null,
        "dc:rights": null,
        "dc:created": "2014-09-18T13:42:16.31Z",
        "dc:title": "Folder 2",
        "dc:issued": null,
        "dc:nature": null,
        "dc:subjects": [],
        "dc:contributors": [
          "Administrator"
        ],
        "dc:source": null,
        "dc:publisher": null
      },
      "facets": [
        "Folderish"
      ],
      "changeToken": "1411047736310",
      "contextParameters": {
        "documentURL": "/nuxeo/nxdoc/test/48706617-f28f-4fd5-9a7c-1b7759908eb9"
      }
    }
..............................
  "aggregations": {
    "coverage": {
      "id": "coverage",
      "type": "terms",
      "query": {
        "field": "dc:coverage",
        "properties": {
          "size": "5"
        },
        "id": "coverage",
        "type": "terms",
        "selection": []
      },
      "buckets": [
        {
          "key": "Coverage0",
          "docCount": 2
        },
        {
          "key": "Coverage1",
          "docCount": 2
        },
        {
          "key": "Coverage2",
          "docCount": 1
        }
      ]
    },
    "nature": {
      "id": "nature",
      "type": "terms",
      "query": {
        "field": "dc:nature",
        "properties": {
          "size": "5"
        },
        "id": "nature",
        "type": "terms",
        "selection": []
      },
      "buckets": [
        {
          "key": "Nature0",
          "docCount": 3
        },
        {
          "key": "Nature1",
          "docCount": 2
        }
      ]
    },
    "source": {
      "id": "source",
      "type": "terms",
      "query": {
        "field": "dc:source",
        "properties": {
          "size": "5"
        },
        "id": "source",
        "type": "terms",
        "selection": []
      },
      "buckets": [
        {
          "key": "Source0",
          "docCount": 1
        },
        {
          "key": "Source1",
          "docCount": 1
        },
        {
          "key": "Source2",
          "docCount": 1
        },
        {
          "key": "Source3",
          "docCount": 1
        },
        {
          "key": "Source4",
          "docCount": 1
        }
      ]
    }
  }
}

Using a parameter

GET http://NUXEO_SERVER/nuxeo/api/v1/search/pp/aggregates_1/execute?nature_agg=%5B%22mynaturevalue1%22%5D

Using a multi-valued parameter

GET http://NUXEO_SERVER/nuxeo/api/v1/search/pp/default_search/execute?dc_creator_agg=%5B%22user1%22,%22user2%22%5D

Using several parameters

GET http://NUXEO_SERVER/nuxeo/api/v1/search/pp/default_search/execute?dc_creator_agg=%5B%22user1%22,%22user2%22%5D&dc_nature_agg=%5B%22mynaturevalue1%22%5D

Managing Saved Searches

Saving a Search by Query

Request

POST http://NUXEO_SERVER/nuxeo/api/v1/search/saved
{
  "entity-type": "savedSearch",
  "title": "search by query",
  "query": "select * from Document where dc:creator = ?",
  "queryLanguage": "NXQL",
  "queryParams": "$currentUser",
  "pageSize": "2"
}

Saving a Search Using a Search Document Model

Request

POST http://NUXEO_SERVER/nuxeo/api/v1/search/saved
{
  "entity-type": "savedSearch",
  "title": "search by search document model",
  "pageProviderName": "default_search",
  "pageSize": "2",
  "params": {
    "ecm_fulltext": "pupp*",
    "dc_modified_agg": ["lastMonth"]
  }
}

Note that the properties of the search document model are passed in the params property.

Saving a Search Using a Page Provider and with Content View Data

Request

POST http://NUXEO_SERVER/nuxeo/api/v1/search/saved
{
  "entity-type": "savedSearch",
  "title": "my search by page provider",
  "pageProviderName": "default_document_suggestion",
  "queryParams": "Puppy",
  "contentViewData": "{\"viewVar\": \"value\"}"
}

Listing Saved Searches

Request

GET http://NUXEO_SERVER/nuxeo/api/v1/search/saved

Response

{
  "entity-type": "savedSearches",
  "entries": [
    {
      "entity-type": "savedSearch",
      "id": "f0c173cc-4bbc-42b1-ac66-51b362643b6c",
      "title": "search by search document model",
      "queryParams": null,
      "query": null,
      "queryLanguage": null,
      "pageProviderName": "default_search",
      "pageSize": "2",
      "currentPageIndex": null,
      "maxResults": null,
      "sortBy": null,
      "sortOrder": null,
      "contentViewData": null,
      "params": {}
    },
    {
      "entity-type": "savedSearch",
      "id": "d9177b09-f077-4d69-bac5-687e3a71c7d1",
      "title": "search by query",
      "queryParams": "$currentUser",
      "query": "select * from Document where dc:creator = ?",
      "queryLanguage": "NXQL",
      "pageProviderName": null,
      "pageSize": "2",
      "currentPageIndex": null,
      "maxResults": null,
      "sortBy": null,
      "sortOrder": null,
      "contentViewData": null,
      "params": {}
    },
    {
      "entity-type": "savedSearch",
      "id": "09b3057f-6222-4567-924c-66fe0dd06140",
      "title": "my search by page provider",
      "queryParams": "Puppy",
      "query": null,
      "queryLanguage": null,
      "pageProviderName": "default_document_suggestion",
      "pageSize": null,
      "currentPageIndex": null,
      "maxResults": null,
      "sortBy": null,
      "sortOrder": null,
      "contentViewData": "{\"viewVar\": \"value\"}",
      "params": {}
    }
  ]
}

Retrieving a Search

Request

GET http://NUXEO_SERVER/nuxeo/api/v1/search/saved/f0c173cc-4bbc-42b1-ac66-51b362643b6c

Response

{
  "entity-type": "savedSearch",
  "id": "f0c173cc-4bbc-42b1-ac66-51b362643b6c",
  "title": "search by search document model",
  "queryParams": null,
  "query": null,
  "queryLanguage": null,
  "pageProviderName": "default_search",
  "pageSize": "2",
  "currentPageIndex": null,
  "maxResults": null,
  "sortBy": null,
  "sortOrder": null,
  "contentViewData": null,
  "params": {}
}

In the above example the search has a search document model, containing its own properties. To display these, pass the desired schemas in the properties header when performing the request.

Request

[HEADER] properties: default_search
GET http://NUXEO_SERVER/nuxeo/api/v1/search/saved/f0c173cc-4bbc-42b1-ac66-51b362643b6c

Response

{
    "contentViewData": null,
    "currentPageIndex": null,
    "entity-type": "savedSearch",
    "id": "f0c173cc-4bbc-42b1-ac66-51b362643b6c",
    "maxResults": null,
    "pageProviderName": "default_search",
    "pageSize": "2",
    "params": {
        "defaults:common_size_agg": [],
        "defaults:dc_coverage": [],
        "defaults:dc_coverage_agg": [],
        "defaults:dc_created_agg": [],
        "defaults:dc_created_max": null,
        "defaults:dc_created_min": null,
        "defaults:dc_creator": [],
        "defaults:dc_creator_agg": [],
        "defaults:dc_modified_agg": [
            "lastMonth"
        ],
        "defaults:dc_modified_max": null,
        "defaults:dc_modified_min": null,
        "defaults:dc_nature": [],
        "defaults:dc_nature_agg": [],
        "defaults:dc_subjects": [],
        "defaults:dc_subjects_agg": [],
        "defaults:ecm_collections": [],
        "defaults:ecm_fulltext": "pupp*",
        "defaults:ecm_path": [],
        "defaults:ecm_tags": []
    },
    "query": null,
    "queryLanguage": null,
    "queryParams": null,
    "sortBy": null,
    "sortOrder": null,
    "title": "search by search document model"
}

Executing a Search

Executing a search with stored parameters:

Request

GET http://NUXEO_SERVER/nuxeo/api/v1/search/saved/f0c173cc-4bbc-42b1-ac66-51b362643b6c/execute

Overriding a stored execution parameters, in this case pageSize:

Request

GET http://NUXEO_SERVER/nuxeo/api/v1/search/saved/f0c173cc-4bbc-42b1-ac66-51b362643b6c/execute?pageSize=5

Learn More

Test these endpoints on your local instance with Nuxeo API Playground (see documentation to configure your local instance).
Checkout the Nuxeo REST API explorer of your instance at http://NUXEO_SERVER/nuxeo/api/v1/doc.