Skip to main content
Ctrl+K

plone-client

  • Get started
    • Script Plone from Python
    • Manage sites from a terminal
    • Work with assistants and coding agents
  • Tutorials
    • Your first script
    • Your first command line session
    • Your first agent session
    • Build an editorial assistant
    • Migrate content between two sites
  • How-to guides
    • Install plone-client
    • Connect to a site
    • Manage profiles
    • Run a Plone site for testing
    • Sync content from an external source
    • Create content in one step
    • Publish a news item with a lead image
    • Build any block
    • Upload and download files
    • Preview changes and protect a site
    • Handle errors
    • Call other services
    • Work with large sites
    • Manage users and sharing
    • Everyday site management
    • Use the command line in scripts and CI
    • Replace a hand-written client
    • Use plone-client with coding agents
    • Connect an assistant through the MCP server
    • Connect Claude Desktop to a Plone site
    • Protect a site from an agent
    • Build a custom agent
    • Troubleshoot
  • Reference
    • Services
      • Content
      • Search
      • Workflow and history
      • Files
      • Navigation
      • Comments, aliases, relations, and translations
      • Users, groups, and sharing
      • Types and vocabularies
      • Site settings
    • PloneClient
    • Managers
    • Operations
    • Block helpers
    • Content model
    • Other modules
    • Map to @plone/client
    • Command line
    • Cheat sheet
    • MCP server
    • Agent skill
    • Compatibility
    • Configuration
    • Exceptions
    • Changelog
  • Explanation
    • About the design of plone-client
    • About profiles and secrets
    • About the command line for coding agents
    • About the MCP server, the command line, and the skill
    • When to call the API directly
  • Glossary
  • Repository
  • Suggest edit
  • Open issue
  • .md

Search

Contents

  • client.search
    • client.search.search
      • Sort, and ask for more metadata
    • client.search.iter
    • client.search.count
  • client.querystring
    • client.querystring.config
    • client.querystring.search

Search#

Find items through the catalog, with SearchManager and QuerystringManager. The first takes keyword arguments and reads @search; the second takes the criteria a Listing block stores. For queries over many items, see Work with large sites.

Each example uses the client from How to read these pages.

client.search#

SearchManager.

Catalog queries through @search.

client.search.search#

One page of results.

See search().

Calls GET /news/@search (plone.restapi documentation).

client.search.search("/news", portal_type="News Item", b_size=2)
plone-client search /news -t "News Item" --limit 2 -f @id,title
[
  {
    "@id": "http://localhost:8080/Plone/news/release-6-2",
    "title": "Release 6.2 is out"
  },
  {
    "@id": "http://localhost:8080/Plone/news/release-party",
    "title": "Release party in Brasília"
  }
]
GET /Plone/++api++/news/@search?portal_type=News+Item&b_size=2 HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET 'http://localhost:8080/Plone/++api++/news/@search?portal_type=News+Item&b_size=2' -H 'accept: application/json' -u admin:admin
{
  "items": [
    {
      "@id": "http://localhost:8080/Plone/news/release-6-2",
      "review_state": "published",
      "title": "Release 6.2 is out"
    },
    {
      "@id": "http://localhost:8080/Plone/news/release-party",
      "review_state": "private",
      "title": "Release party in Brasília"
    }
  ],
  "items_total": 5
}

This shows only items, items_total. This shows only @id, title, review_state of each entry.

Sort, and ask for more metadata#

query takes options of a catalog index, and metadata_fields adds columns to each result.

Calls GET /@search (plone.restapi documentation).

client.search.search(
    query={"created": {"query": "2000-01-01", "range": "min"}},
    portal_type="Document",
    sort_on="sortable_title",
    metadata_fields="UID",
)
GET /Plone/++api++/@search?created.query=2000-01-01&created.range=min&portal_type=Document&sort_on=sortable_title&metadata_fields=UID HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET 'http://localhost:8080/Plone/++api++/@search?created.query=2000-01-01&created.range=min&portal_type=Document&sort_on=sortable_title&metadata_fields=UID' -H 'accept: application/json' -u admin:admin
{
  "items": [
    {
      "UID": "3788c6ac13e749709aa4f2fb771821ce",
      "title": "About"
    },
    {
      "UID": "4bf216176ffc4aa1ac76407db4d0202a",
      "title": "Media"
    }
  ],
  "items_total": 5
}

This shows only items, items_total. This shows only title, UID of each entry. This shows 2 of 5 entries.

client.search.iter#

Every result, fetching the pages as needed.

See iter().

Calls GET /@search (plone.restapi documentation).

list(client.search.iter(portal_type="News Item", review_state="private"))
plone-client search -t "News Item" --state private -f @id
[
  {
    "@id": "http://localhost:8080/Plone/news/release-party"
  },
  {
    "@id": "http://localhost:8080/Plone/news/release-notes-draft"
  }
]
GET /Plone/++api++/@search?portal_type=News+Item&review_state=private&b_size=100 HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET 'http://localhost:8080/Plone/++api++/@search?portal_type=News+Item&review_state=private&b_size=100' -H 'accept: application/json' -u admin:admin
[
  {
    "@id": "http://localhost:8080/Plone/news/release-party",
    "title": "Release party in Brasília"
  },
  {
    "@id": "http://localhost:8080/Plone/news/release-notes-draft",
    "title": "Release notes draft"
  }
]

This shows only @id, title of each entry.

client.search.count#

Number of results of a search.

See count().

Calls GET /news/@search (plone.restapi documentation).

client.search.count("/news", review_state="published")
plone-client search /news --state published --count
{
  "items_total": 3
}
GET /Plone/++api++/news/@search?review_state=published&b_size=1 HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET 'http://localhost:8080/Plone/++api++/news/@search?review_state=published&b_size=1' -H 'accept: application/json' -u admin:admin
3

client.querystring#

QuerystringManager.

Collection-style queries through @querystring-search.

client.querystring.config#

Indexes, operators and sort options the querystring accepts.

See config().

Calls GET /@querystring (plone.restapi documentation).

sorted(client.querystring.config()["sortable_indexes"])[:3]
GET /Plone/++api++/@querystring HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/@querystring -H 'accept: application/json' -u admin:admin
[
  "Creator",
  "created",
  "effective"
]

client.querystring.search#

Run a querystring query.

See search().

Calls POST /@querystring-search (plone.restapi documentation).

client.querystring.search(
    [
        {
            "i": "portal_type",
            "o": "plone.app.querystring.operation.selection.any",
            "v": ["News Item"],
        }
    ],
    sort_on="sortable_title",
    b_size=2,
)
POST /Plone/++api++/@querystring-search HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "query": [
    {
      "i": "portal_type",
      "o": "plone.app.querystring.operation.selection.any",
      "v": [
        "News Item"
      ]
    }
  ],
  "sort_on": "sortable_title",
  "b_size": 2
}
curl -i -X POST http://localhost:8080/Plone/++api++/@querystring-search -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"query":[{"i":"portal_type","o":"plone.app.querystring.operation.selection.any","v":["News Item"]}],"sort_on":"sortable_title","b_size":2}'
{
  "items": [
    {
      "@id": "http://localhost:8080/Plone/news/old-announcement",
      "title": "Old announcement"
    },
    {
      "@id": "http://localhost:8080/Plone/news/release-6-2",
      "title": "Release 6.2 is out"
    }
  ],
  "items_total": 5
}

This shows only items, items_total. This shows only @id, title of each entry.

previous

Content

next

Workflow and history

Contents
  • client.search
    • client.search.search
      • Sort, and ask for more metadata
    • client.search.iter
    • client.search.count
  • client.querystring
    • client.querystring.config
    • client.querystring.search

By Plone Community

© Copyright 2026.