REST API

Query Endpoint

The query endpoint allows REST clients to query the Nuxeo repository.

Endpoint

Path Endpoint
GET /api/v1/query /api/v1/query/NXQL Endpoint to perform queries on the repository in NXQL.
GET /api/v1/query/{providerName} Endpoint to perform a query based on page provider registered on the application.

Properties

Key Value
query string The query to perform. By default: SELECT * FROM Document
pageSize integer The number of entries per page. By default: 0 (0 means no pagination.) The maximum number of entries per page is 1000 by default. See nuxeo.pageprovider.default-max-page-size to customize it.
currentPageIndex integer The selected page index. By default: 0
maxResults integer The maximum entries. By default: 200
sortBy string Property(ies) sorting. Example: sortBy="dc:title,dc:description"
sortOrder string Sort order. Values: ASC or DESC Example: sortOrder="DESC,ASC"
queryParams string Ordered parameters. Example: for a query pattern like Select * From Document where [dc:title](http://dctitle) = ? , the queryParams value should be "my title", for instance. Note this is only interesting 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](http://dctitle) = :title1, the title1 parameter should be "my title", for instance. Parameter names should be strictly different from property names (and other query parameters). Note this is only interesting when using a page provider, defined server side.

Examples

Query

Examples

http://NUXEO_SERVER/nuxeo/site/api/v1/query?query=select * from Document

http://NUXEO_SERVER/nuxeo/site/api/v1/query?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"
            }
        }
    ]
}

Query - Elasticsearch

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

elasticsearch.override.pageproviders=default_search,REST_API_SEARCH_ADAPTER

Note that the 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 else it won't be querying Elasticsearch anymore.

See also How to Make a Page Provider or Content View Query Elasticsearch Index.

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 when defining page providers and making it possible to pass parameters from the client.

Page Provider without Parameters

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

Example

http://NUXEO_SERVER/nuxeo/site/api/v1/query/latest_docs

Page Provider with 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:currentLifeCycleState != 'deleted'
  </pattern>
  <sort column="dc:title" ascending="true" />
  <pageSize>50</pageSize>
</coreQueryPageProvider>

Example

http://NUXEO_SERVER/nuxeo/site/api/v1/query/tree_children?queryParams=47dd6d8d-d8d0-4a09-9e3e-e30fc8877df1

Page Provider with 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

http://NUXEO_SERVER/nuxeo/site/api/v1/query/docs_by_title_and_desc?title=mytitle&desc=mydesc

Page provider with 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

http://NUXEO_SERVER/nuxeo/site/api/v1/query/docs_by_title_if_any?title=mytitle
http://NUXEO_SERVER/nuxeo/site/api/v1/query/docs_by_title_if_any

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

Named parameters will be, by default, treated as String values. If you need further configuration, you'll need to define a document type, and associated schema, so that conversions are accurate for numbers, dates, booleans, etc...

Page Provider with Named Parameter in WHERE Clause and Typing

Assuming a document type NamedParamDoc, with associated schema with prefix np, has 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

http://NUXEO_SERVER/nuxeo/site/api/v1/query/docs_by_title_complex?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"
            }
        }
    ]
}

Page Provider - 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

http://NUXEO_SERVER/nuxeo/api/v1/query/aggregates_1

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
        }
      ]
    }
  }
}

22 days ago Andrew Goodricke Syntax error fixed
4 years ago Manon Lumeau 29
4 years ago Solen Guitter 28 | Update related pages
4 years ago Solen Guitter 27
5 years ago Anahide Tchertchian 26 | fill doc with named parameters examples
5 years ago Anahide Tchertchian 25
5 years ago Anahide Tchertchian 24 | format + add related content
5 years ago Guillaume Renard 23
5 years ago Vladimir Pasquier 22
5 years ago Solen Guitter 20
5 years ago Solen Guitter 21
5 years ago Vladimir Pasquier 19 | add es provider
5 years ago Vladimir Pasquier 18
5 years ago Vladimir Pasquier 17
5 years ago Vladimir Pasquier 16
5 years ago Thibaud Arguillere 15
5 years ago Vladimir Pasquier 14 | Query Endpoint
5 years ago Vladimir Pasquier 13
5 years ago Vladimir Pasquier 12
5 years ago Vladimir Pasquier 11
5 years ago Vladimir Pasquier 9
5 years ago Vladimir Pasquier 10
5 years ago Vladimir Pasquier 8
5 years ago Vladimir Pasquier 7
5 years ago Vladimir Pasquier 6
5 years ago Vladimir Pasquier 4
5 years ago Vladimir Pasquier 5
5 years ago Solen Guitter 3
5 years ago Vladimir Pasquier 2 | wip query endpoint
5 years ago Vladimir Pasquier 1
History: Created by Vladimir Pasquier

We'd love to hear your thoughts!

All fields required