logo

Plone Documentation v6.0-dev

  • Backend
    • Content Types
    • Behaviors
    • Annotations
    • Vocabularies
    • Fields
    • Widgets
    • plone_view/utils (global functions CMFPlone/plone.app.layout)
    • Portal Actions
    • Users and Groups
    • Security
    • Workflows
    • Search
    • ZODB
    • plone.api
    • plone.restapi
    • Sending Email
    • Upgrading the Backend
      • Upgrading to Plone 6.0
  • Frontend
    • Introduction
      • Getting Started
      • Developer roadmap
      • Other learning resources
    • Configuration
      • The configuration registry
      • Settings reference guide
      • Zero configuration builds
      • Internal proxy to content backend API
      • Backend configuration
      • Dynamic Volto Addons Configuration
      • RichEditor Settings
      • Multilingual
      • Working copy support
      • Environment variables
      • API expanders
      • Locking support
    • Theming
      • About Semantic UI
      • Semantic Theming
      • How does the theming engine work?
      • Theming Strategy
      • Custom Styling
      • Using third party libraries/themes different from semantic-ui
    • Development recipes
      • Creating a new Volto project
      • Folder structure
      • How to use environment variables
      • Customizing Components
      • Customizing Volto Views
      • Creating Volto Views
      • Internationalization
      • Custom Express middleware
      • Lazy loading
      • AppExtras component
      • Context navigation component
      • Pluggables framework
      • Forms and widgets
      • Legacy Browser Support (IE11 compatibility)
    • Blocks
      • Blocks
      • Blocks anatomy
      • Blocks settings
      • Blocks - Edit components
      • Block extensions mechanism
      • Server-side rendering for async blocks
    • Volto add-ons
      • Add-on Internationalization
      • Best practices for add-ons
    • Integration with the backend
    • Deploying
      • Simple deployment
      • Deployment using a node process manager (pm2)
      • Seamless mode
      • Apache
      • Integration with Sentry
      • critical.css (above the fold) optimizations
    • Upgrade Guide
    • Developer Guidelines
      • Design principles
      • Style Guide
      • Language features and conventions
      • Linting
      • React
      • Redux
      • Routing
      • Testing
      • Acceptance tests
      • Accessibility guidelines
      • TypeScript
    • Design principles
      • Guidelines
  • Classic UI
    • Static Resources
    • Plone 6 Classic UI Theming
      • Plone Classic UI Theming Based on Barceloneta
      • Plone Classic UI Theming with Diazo
      • Plone Classic UI Theming based on Barceloneta
      • Through-the-web (TTW) Theme Customization in Plone 6 Classic UI
    • Templates
    • Views
    • Viewlets
    • Forms
    • Portlets
    • Cross-Site Request Forgery (CSRF)
    • Image handling
    • Icons in Plone 6 Classic UI
    • Recipes
    • What's new in Plone 6 Classic UI
  • REST API
    • Introduction
      • More on Content Negotiation
      • Representation of all standard Plone contenttypes
    • Authentication
    • Explore the API using Postman
    • Content Manipulation
    • Volto Blocks support
    • History
    • Batching
    • Add-ons
    • Comments
    • Copy / Move
    • Expansion
    • Portal Actions
    • Workflow
    • Working Copy
    • Locking
    • Sharing
    • Registry
    • Types
    • Types Schema
    • Users
    • Groups
    • Principals
    • Roles
    • Breadcrumbs
    • Navigation
    • Context Navigation
    • Serialization
    • Search
    • TUS resumable upload
    • Vocabularies and Sources
    • Control Panels
    • Tiles
    • Querystring
    • Querystring Search
    • Customizing the API
    • Conventions
    • Translations
    • Email Send
    • i18n: internationalization of screen messages
    • Email Notification
    • Upgrade Guide
    • Contributing to plone.restapi
    • System
    • Database
    • HTTP Status Codes
    • Glossary
  • Contributing to Plone Documentation
    • Building and Checking the Quality of Documentation
    • General Guide to Writing Documentation
    • Authors Guide
    • Administrators Guide

Appendices

  • Glossary

plone.org plone.org

  • repository
  • open issue
  • suggest edit
  • .rst
Contents
  • Parameters
    • Batch Start (b_start)
    • Batch Size (b_size)
    • Sort on
    • Sort Order
    • Limit
  • Query
    • Metadata Filters
      • Creator
      • 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

Contents

  • Parameters
    • Batch Start (b_start)
    • Batch Size (b_size)
    • Sort on
    • Sort Order
    • Limit
  • Query
    • Metadata Filters
      • Creator
      • 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 : "ascending", "descending" (string)

  • limit (integer, limits the number of returned results)

  • fullobjects : "true", "false" (boolean, if true the 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 and 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. And 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’, where ‘ascending’ means from A to Z for a text field. ‘reverse’ is an alias equivalent to ‘descending’.

Limit#

Querystring Query with 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 this filter is applied to)

  • o: the operator of the filter (the operator, a full list can be found here: https://github.com/plone/plone.app.querystring/blob/master/plone/app/querystring/profiles/default/registry.xml)

  • v: the value of the filter (this highly depends on the index, for a text index, this is a string, for a date index this might be a date range)

The following type 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 (the id of the object that is shown as 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 (relative 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 path can be stored computed:

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

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

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

Customizing the API

By the Plone community
© Copyright 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