Querystring Search

Querystring Search#

The @querystring-search endpoint returns search results that can be filtered on search criteria.

Call the /@querystring-search endpoint with either a POST or GET request.

When using the POST request, provide a query in the request body:

http

POST /plone/@querystring-search HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "query": [
        {
            "i": "portal_type",
            "o": "plone.app.querystring.operation.selection.any",
            "v": [
                "Document"
            ]
        }
    ]
}

curl

curl -i -X POST http://nohost/plone/@querystring-search -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"query": [{"i": "portal_type", "o": "plone.app.querystring.operation.selection.any", "v": ["Document"]}]}' --user admin:secret

httpie

echo '{
  "query": [
    {
      "i": "portal_type",
      "o": "plone.app.querystring.operation.selection.any",
      "v": [
        "Document"
      ]
    }
  ]
}' | http POST http://nohost/plone/@querystring-search Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/@querystring-search', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'query': [{'i': 'portal_type', 'o': 'plone.app.querystring.operation.selection.any', 'v': ['Document']}]}, auth=('admin', 'secret'))

The server will respond with the results that are filtered based on the query you provided:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@id": "http://localhost:55001/plone/@querystring-search",
    "items": [
        {
            "@id": "http://localhost:55001/plone/front-page",
            "@type": "Document",
            "description": "Congratulations! You have successfully installed Plone.",
            "review_state": "private",
            "title": "Welcome to Plone",
            "type_title": "Page"
        },
        {
            "@id": "http://localhost:55001/plone/testdocument",
            "@type": "Document",
            "description": "",
            "review_state": "private",
            "title": "Test Document",
            "type_title": "Page"
        }
    ],
    "items_total": 2
}

When using the GET request, provide the query as a JSON URL-encoded string as a parameter.

http

GET /plone/@querystring-search?query=%257B%2522query%2522%253A%255B%257B%2522i%2522%253A%2522portal_type%2522%252C%2522o%2522%253A%2520%2522plone.app.querystring.operation.selection.any%2522%252C%2522v%2522%253A%255B%2522Document%2522%255D%257D%255D%257D HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X GET 'http://nohost/plone/@querystring-search?query=%257B%2522query%2522%253A%255B%257B%2522i%2522%253A%2522portal_type%2522%252C%2522o%2522%253A%2520%2522plone.app.querystring.operation.selection.any%2522%252C%2522v%2522%253A%255B%2522Document%2522%255D%257D%255D%257D' -H "Accept: application/json" --user admin:secret

httpie

http 'http://nohost/plone/@querystring-search?query=%257B%2522query%2522%253A%255B%257B%2522i%2522%253A%2522portal_type%2522%252C%2522o%2522%253A%2520%2522plone.app.querystring.operation.selection.any%2522%252C%2522v%2522%253A%255B%2522Document%2522%255D%257D%255D%257D' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@querystring-search?query=%257B%2522query%2522%253A%255B%257B%2522i%2522%253A%2522portal_type%2522%252C%2522o%2522%253A%2520%2522plone.app.querystring.operation.selection.any%2522%252C%2522v%2522%253A%255B%2522Document%2522%255D%257D%255D%257D', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

The server will respond with the results that are filtered based on the query you provided:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@id": "http://localhost:55001/plone/@querystring-search?query=%257B%2522query%2522%253A%255B%257B%2522i%2522%253A%2522portal_type%2522%252C%2522o%2522%253A%2520%2522plone.app.querystring.operation.selection.any%2522%252C%2522v%2522%253A%255B%2522Document%2522%255D%257D%255D%257D",
    "items": [
        {
            "@id": "http://localhost:55001/plone/front-page",
            "@type": "Document",
            "description": "Congratulations! You have successfully installed Plone.",
            "review_state": "private",
            "title": "Welcome to Plone",
            "type_title": "Page"
        },
        {
            "@id": "http://localhost:55001/plone/testdocument",
            "@type": "Document",
            "description": "",
            "review_state": "private",
            "title": "Test Document",
            "type_title": "Page"
        }
    ],
    "items_total": 2
}

Virtual Host Monster Support#

When accessed through a Virtual Host Monster (VHM), the endpoint automatically resolves virtual paths provided in the query criteria to their physical counterparts in the catalog.

For example, if your Plone site is physically located at /Plone but served at http://plone.org/, a query for v: "/folder" will be automatically expanded to /Plone/folder before being passed to the catalog.

This expansion applies to any value in a path criterion that starts with a /. It also correctly handles the ::depth suffix.

Parameters the endpoint will accept:

query - plone.app.querystring query, required
b_start - integer, batch start
b_size - integer, batch size
sort_on - string, field that results will be sorted on
sort_order - string, value must be either ascending or descending
limit - integer, limits the number of returned results
fullobjects - boolean, if true then return the full objects instead of just the summary serialization

Changed in version plone.restapi: 10.0.0

Since plone.restapi version 10.0.0, boolean parameters are validated more strictly.

See Parameters for details.

Parameters#

Batch Start (`b_start`)#

The b_start parameter defines the first item of the batch:

{
  "b_start": "5",
  "query": [
    {
      'i': 'Title',
      'o': 'plone.app.querystring.operation.string.is',
      'v': 'Welcome to Plone',
    }
  ]
}

The b_size parameter is optional. The default value is 0.

Batch Size (b_size)#

The b_size parameter defines the number of elements a single batch returns:

{
  "b_size": "5",
  "query": [
    {
      'i': 'Title',
      'o': 'plone.app.querystring.operation.string.is',
      'v': 'Welcome to Plone',
    }
  ]
}

The parameter is optional. The default value is 25.

Sort on#

The sort_on parameter defines the field that is used to sort the returned search results:

{
  "sort_on": "sortable_title",
  "query": [
    {
      'i': 'Title',
      'o': 'plone.app.querystring.operation.string.is',
      'v': 'Welcome to Plone',
    }
  ]
}

The sort_on parameter is optional. The default value is None.

Sort Order#

The sort_order parameter defines the sort order when the sort_on field has been set:

{
  "sort_on": "sortable_title",
  "sort_order": "reverse",
  "query": [
    {
      'i': 'Title',
      'o': 'plone.app.querystring.operation.string.is',
      'v': 'Welcome to Plone',
    }
  ]
}

The sort_order parameter is optional. The default value is ascending.

The sort_order can be either ascending or descending. ascending means from A to Z for a text field. reverse is an alias equivalent to descending.

Limit#

Use the limit parameter to set a maximum number of results that will be returned:

{
  "limit": "10",
  "query": [
    {
      'i': 'Title',
      'o': 'plone.app.querystring.operation.string.is',
      'v': 'Welcome to Plone',
    }
  ]
}

The limit parameter is optional. The default value is None, but a single page of results will still have a size determined by the batch size parameter b_size.

Query#

The query parameter is a list that contains an arbitrary number of filters:

{
  "query": [
    {
      'i': 'Title',
      'o': 'plone.app.querystring.operation.string.is',
      'v': 'Welcome to Plone',
    }
  ]
}

A filter always contains three values:

ì: The index of the filter (the name of the field to which this filter is applied).
o: The operator of the filter. A full list can be found at plone/plone.app.querystring.
v: The value of the filter. This depends highly on the index. For a text index, this is a string. For a date index, this might be a date range.

The following types of filters are available:

Metadata filters
Date filters
Text Filters

Metadata Filters#

Creator#

The creator of the content object.

You can either set the currently logged in user:

{
  "query":[
    {
      "i":"Creator",
      "o":"plone.app.querystring.operation.string.currentUser",
      "v":""
    }
  ],
}

…or set a username:

{
  "query":[
    {
      "i":"Creator",
      "o":"plone.app.querystring.operation.selection.any",
      "v":["noam"]
    }
  ]
}

Shortname#

Shortname is the ID of the object that is shown as the last part of the URL:

{
  "query":[
    {
      "i":"getId",
      "o":"plone.app.querystring.operation.string.is",
      "v":"hero"
    }
  ]
}

Location#

Location is the path of the content object on the site. You can either set three kind of paths.

The absolute path from the portal root:

{
  "query":[
    {
      "i":"path",
      "o":"plone.app.querystring.operation.string.absolutePath",
      "v":"/my-content-object"
    }
  ]
}

The relative path from the current object:

{
  "query":[
    {
      "i":"path",
      "o":"plone.app.querystring.operation.string.relativePath",
      "v":"../my-content-object"
    }
  ]
}

The navigation path:

{
  "query":[
    {
      "i":"path",
      "o":"plone.app.querystring.operation.string.path",
      "v":"/hero"
    }
  ]
}

The computed path can be stored:

{
  "query": [
    {
      'i': 'path',
      'o': 'plone.app.querystring.operation.string.path',
      'v': '00000000000000001',
    }
  ]
}

The path can contain a depth parameter that is separated with :::

{
  "query": [
    {
      'i': 'path',
      'o': 'plone.app.querystring.operation.string.path',
      'v': '/my-content-object::2',
    }
  ]
}

Type#

Filter by portal type:

{
  "query": [
    {
      "i": "portal_type",
      "o": "plone.app.querystring.operation.selection.any",
      "v": ["Document"],
    }
  ]
}

Review State#

Filter results by review state:

{
  "query":[
    {
      "i":"review_state",
      "o":"plone.app.querystring.operation.selection.any",
      "v":["published"]
    }
  ]
}

Show Inactive#

Show inactive will return content objects that is expired for a given role:

{
  "query":[
    {
      "i":"show_inactive",
      "o":"plone.app.querystring.operation.string.showInactive",
      "v":["Owner"]
    }
  ]
}

Text Filters#

Description#

Filter content that contains a term in the Description field:

{
  "query":[
    {
      "i":"Description",
      "o":"plone.app.querystring.operation.string.contains",
      "v":"Noam"
    }
  ]
}

Searchable Text#

Filter content that contains a term in the SearchableText (all searchable fields in the catalog):

{
  "query":[
    {
      "i":"SearchableText",
      "o":"plone.app.querystring.operation.string.contains",
      "v":"Noam"
    }
  ]
}

Tag#

Filter by a tag (subjects field):

{
  "query":[
    {
      "i":"Subject",
      "o":"plone.app.querystring.operation.selection.any",
      "v":["Astrophysics"]
    }
  ]
}

Title#

Filter by exact Title match:

"query": [
  {
    'i': 'Title',
    'o': 'plone.app.querystring.operation.string.is',
    'v': 'Welcome to Plone',
  }
]

Date Filters#

Creation Date#

Filter by creation date:

{
  "query":[
    {
      "i": "created",
      "o": "plone.app.querystring.operation.date.lessThan",
      "v": "2021-11-11"
    }
  ]
}

Effective Date#

Filter by effective date:

{
  "query":[
    {
      "i": "effective",
      "o": "plone.app.querystring.operation.date.largerThan",
      "v": "2021-11-11"
      }
    }
  ]
}

Event end date#

Filter by event end date:

{
  "query":[
    {
      "i": "end",
      "o": "plone.app.querystring.operation.date.lessThan",
      "v":"2021-11-04"
    }
  ]
}

Event start date#

Filter by event start date:

{
  "query":[
    {
      "i": "end",
      "o": "plone.app.querystring.operation.date.lessThan",
      "v":"2021-11-04"
    }
  ]
}

Expiration date#

Filter by expiration date:

{
  "query":[
    {
      "i": "expires",
      "o": "plone.app.querystring.operation.date.largerThan",
      "v": "2021-11-11"
      }
    }
  ]
}

Modification date#

Filter by modification date:

{
  "query":[
    {
      "i": "modified",
      "o": "plone.app.querystring.operation.date.largerThan",
      "v": "2021-11-11"
      }
    }
  ]
}