Ctrl+K
Logo image

Table of Contents

  • Introduction
  • Usage
    • Authentication
    • Batching
    • Content Manipulation
    • Customizing the API
    • Explore the API using Postman
    • i18n: internationalization of screen messages
    • Serialization
    • Sharing
    • Types Schema
    • Volto Blocks support
  • Endpoints
    • Add-ons
    • Aliases
    • Breadcrumbs
    • Comments
    • Content Types
    • Content Rules
    • Context Navigation
    • Control Panels
    • Copy and Move
    • Database
    • Email Notification
    • Email Send
    • Expansion
    • Groups
    • History
    • Link Integrity
    • Locking
    • Navigation
    • Portal Actions
    • Portraits
    • Principals
    • Querystring
    • Querystring Search
    • Registry
    • Roles
    • Search
    • System
    • Tiles
    • Transactions
    • Translations
    • TUS resumable upload
    • Types
    • Upgrade
    • Users
    • User schema
    • Vocabularies and Sources
    • Workflow
    • Working Copy
  • Upgrade Guide
  • Contributing to plone.restapi
    • Conventions
  • HTTP Status Codes
  • Glossary
  • Repository
  • Suggest edit
  • Open issue
  • .md

Querystring Search

Contents

  • Parameters
    • Batch Start (b_start)
    • Batch Size (b_size)
    • Sort on
    • Sort Order
    • Limit
    • Query
      • Metadata Filters
        • Creator
        • Shortname
        • Location
        • Type
        • Review State
        • Show Inactive
      • Text Filters
        • Description
        • Searchable Text
        • Tag
        • Title
      • Date Filters
        • Creation Date
        • Effective Date
        • Event end date
        • Event start date
        • Expiration date
        • Modification date

Querystring Search#

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

Call the /@querystring-search endpoint with a POST request and 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"
        },
        {
            "@id": "http://localhost:55001/plone/testdocument",
            "@type": "Document",
            "description": "",
            "review_state": "private",
            "title": "Test Document"
        }
    ],
    "items_total": 2
}

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

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#

Querystring query with a limit parameter:

{
  "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 1000.

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

previous

Querystring

next

Registry

Contents
  • Parameters
    • Batch Start (b_start)
    • Batch Size (b_size)
    • Sort on
    • Sort Order
    • Limit
    • Query
      • Metadata Filters
        • Creator
        • Shortname
        • Location
        • Type
        • Review State
        • Show Inactive
      • Text Filters
        • Description
        • Searchable Text
        • Tag
        • Title
      • Date Filters
        • Creation Date
        • Effective Date
        • Event end date
        • Event start date
        • Expiration date
        • Modification date

© Copyright 2014-2023, Plone Foundation.

The text and illustrations in this website are licensed by the Plone Foundation under a Creative Commons Attribution 4.0 International license. Plone and the Plone® logo are registered trademarks of the Plone Foundation, registered in the United States and other countries. For guidelines on the permitted uses of the Plone trademarks, see https://plone.org/foundation/logo. All other trademarks are owned by their respective owners.

Deploys by Netlify