Nuxeo Server

Query Endpoint (Deprecated)

Updated: November 13, 2017 Page Information Edit on GitHub

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

Since 8.3 this endpoint has been deprecated in favor of the Search Resource Endpoint.

Reminder

Automation

Since Nuxeo 6.0, you can use Automation operations remotely to run Page Providers in Elasticsearch.

There are no means to directly execute queries on Elasticsearch through Automation. Use the following Query endpoint instead: Document.PageProvider gives the ability to run page provider on Elasticsearch by passing the parameter providerName. This provider has to be created (for instance myPageProviderESQL and has to be set in $NUXEO_HOME/bin/nuxeo.conf.

elasticsearch.override.pageproviders=default_search,myPageProviderESQL

REST API

Read the following documentation to use the Query endpoint.

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 = ?, 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 = :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

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

GET http://NUXEO_SERVER/nuxeo/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:isCheckedInVersion = 0 AND ecm:currentLifeCycleState != 'deleted'
  </pattern>
  <sort column="dc:modified" ascending="false" />
  <pageSize>50</pageSize>
</coreQueryPageProvider>

Example

GET http://NUXEO_SERVER/nuxeo/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:isCheckedInVersion = 0 AND ecm:currentLifeCycleState != 'deleted'
  </pattern>
  <sort column="dc:title" ascending="true" />
  <pageSize>50</pageSize>
</coreQueryPageProvider>

Example

GET http://NUXEO_SERVER/nuxeo/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

GET http://NUXEO_SERVER/nuxeo/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>

Examples

GET http://NUXEO_SERVER/nuxeo/api/v1/query/docs_by_title_if_any?title=mytitle
GET http://NUXEO_SERVER/nuxeo/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:isCheckedInVersion" 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/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

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

4 days ago manonlumeau Added content-review-lts2017 label
a month ago manonlumeau NXDOC-1346-FT review screenshot
a year ago Gabriel Barata 41
a year ago Gabriel Barata 40
a year ago Manon Lumeau 39
2 years ago Karin Touchie 37
2 years ago Karin Touchie 38
2 years ago Manon Lumeau 36
2 years ago Manon Lumeau 35
3 years ago Solen Guitter 34
3 years ago Solen Guitter 33
3 years ago Solen Guitter 32
3 years ago Solen Guitter 31
3 years ago Vladimir Pasquier 30
3 years ago Anahide Tchertchian 29 | format
3 years ago Anahide Tchertchian 28 | remove leftover chapters
3 years ago Anahide Tchertchian 27 | fill doc with named parameters examples
3 years ago Anahide Tchertchian 26 | add related content + link to interesting page
3 years ago Anahide Tchertchian 25 | format
3 years ago Anahide Tchertchian 24 | remove dupe content (bad previous copy/paste)
3 years ago Guillaume Renard 23
3 years ago Vladimir Pasquier 22
3 years ago Solen Guitter 20
3 years ago Solen Guitter 21
3 years ago Vladimir Pasquier 19 | add es provider
3 years ago Vladimir Pasquier 18
3 years ago Vladimir Pasquier 17
3 years ago Vladimir Pasquier 16
3 years ago Thibaud Arguillere 15
3 years ago Vladimir Pasquier 14 | Query Endpoint
3 years ago Vladimir Pasquier 13
3 years ago Vladimir Pasquier 12
3 years ago Vladimir Pasquier 11
3 years ago Vladimir Pasquier 9
3 years ago Vladimir Pasquier 10
3 years ago Vladimir Pasquier 8
3 years ago Vladimir Pasquier 7
3 years ago Vladimir Pasquier 6
3 years ago Vladimir Pasquier 4
3 years ago Vladimir Pasquier 5
3 years ago Solen Guitter 3
3 years ago Vladimir Pasquier 2 | wip query endpoint
3 years ago Vladimir Pasquier 1
History: Created by Vladimir Pasquier