Searching¶
Search Criteria¶
Pulp offers a standard set of criteria for searching through collections as well as for specifying resources in a collection to act upon.
Any API that supports this criteria will accept a JSON document with a criteria field. The criteria field is a JSON object; the following fields may be present in the criteria object:
- filters
- sort
- limit
- skip
- fields
The filters field is itself a document that specifies, using the pymongo find specification syntax, the resource fields and values to match. For more information on the syntax, see: http://www.mongodb.org/display/DOCS/Querying
Pulp supports an operator extension for matching date fields. The $date
operator may be used to specify ISO-8601 date strings for fields that are
stored as a Date or ISODate (instead of string) in the database.
For example:
{"created": {"$gt": {"$date": "2015-01-01T00:00:00Z"}}}
The sort field is an array of arrays. Each specifying a field and a direction.
The limit field is a number that gives the maximum amount of resources to select. Useful for pagination.
The skip field is a number that gives the index of the first resource to select. Useful for pagination.
The fields field is an array of resource field names to return in the results.
Example search criteria:
{
"criteria": {
"filters": {"id": {"$in": ["fee", "fie", "foe", "foo"]}, "group": {"$regex": ".*-dev"}},
"sort": [["id", "ascending"], ["timestamp", "descending"]],
"limit": 100,
"skip": 0,
"fields": ["id", "group", "description", "timestamp"]}
}
Unit Association Criteria¶
The criteria when dealing with units in a repository is slightly different from the standard model. The metadata about the unit itself is split apart from the metadata about when and how it was associated to the repository. This split occurs in the filters, sort, and fields sections.
The valid fields that may be used in the association sections are as follows:
created- Timestamp in iso8601 format indicating when the unit was first associated with the repository.updated- Timestamp in iso8601 format indicating when the unit was most recently confirmed to be in the repository.
Example unit association criteria:
{
'type_ids' : ['rpm'],
'filters' : {
'unit' : <mongo spec syntax>,
'association' : <mongo spec syntax>
},
'sort' : {
'unit' : [ ['name', 'ascending'], ['version', 'descending'] ],
'association' : [ ['created', 'descending'] ]
},
'limit' : 100,
'skip' : 200,
'fields' : {
'unit' : ['name', 'version', 'arch'],
'association' : ['created']
},
'remove_duplicates' : True
}
Search API¶
The search API is consistent for various data types. Please see the documentation for each individual resource type for information about extra parameters and behaviors specific to that type.
Searching can be done via a GET or POST request, and both utilize the concepts of Search Criteria.
The most robust way to do a search is through a POST request, including a JSON- serialized representation of a Critera in the body under the attribute name “criteria”. This is useful because some filter syntax is difficult to serialize for use in a URL.
Returns items from the Pulp server that match your search parameters. It is worth noting that this call will never return a 404; an empty array is returned in the case where there are no items in the database.
/pulp/api/v2/<resource type>/search/- 200 - containing the list of items
The GET method is slightly more limiting than the POST alternative because some filter expressions may be difficult to serialize as query parameters.
/pulp/api/v2/<resource type>/search/For example:
/pulp/api/v2/<resource type>/search/?field=id&field=display_name&limit=20
- 200 - containing the array of items