Skip to main content

Search objects

post
/api/pvlt/1.0/data/collections/{collection}/query/objects

Returns a paginated list of objects, with property values, from a collection that satisfies a query.

You can read more about full-match searches in the Search objects guide and about substring searches in the Substring search objects guide.

The role performing this operation must have all the following:

  • The CapDataSearcher capability.
  • Policies:
    • At least one allowing policy and no denying policies for the read operation for each of the collection properties specified in the props query parameter.
    • At least one allowing policy and no denying policies for the search operation for each of the collection properties specified in the query body parameter.

See identity and access management for more information about how capabilities are used to control access to operations and policies are used to control access to data.

Warning: Use of the unsafe option, to include all object property values, may expose more private information than is required, use with caution..

Request​

Header parameters​

  • X-Trans-Param - string

    Extra parameter to pass on to the transformers.

  • X-Tenant-Id - array of strings

    List of tenant IDs to enforce on the request.

Path parameters​

  • collection - string required*

    The name of a collection.

Query parameters​

  • adhoc_reason - string

    An ad-hoc reason for accessing the Vault data. Required when reason is set to Other.

  • reason - string required*

    Details of the reason for requesting the property. The default is set when no access reason is provided and PVAULT_SERVICE_FORCE_ACCESS_REASON is false.

  • custom_audit - string

    Custom audit information to be included in the audit log.

  • reload_cache - boolean

    Reloads the cache before the action.

  • page_size - integer

    The maximum number of items to return in this request. If not specified, the default value is used. The default value is specified in the PVAULT_SERVICE_DEFAULT_PAGE_SIZE environment variable. Must not exceed the value specified in the PVAULT_SERVICE_MAX_PAGE_SIZE environment variable.

  • cursor - string

    The cursor represents the state of consecutive queries for the same request parameters. In the first call, the cursor may be omitted or specified as an empty string. In consecutive calls, it should be set to the value of the cursor field of the objectFieldsPage returned by the previous call. Note: when the id is specified, paging is not supported. In this case, if the number of id values specified exceeds the maximum page size, the method returns 400 (BAD REQUEST).

  • options - array of strings

    Options for the operation. Options include:

    • archived – whether to search only archived objects. If not specified, search only active objects.
    • show_builtins – show built-in properties, can only be specified with unsafe.
    • unsafe – fetch all the properties, cannot be specified with props.
    Each string:
  • props - array of strings

    The list of property names and transformations. To include multiple names and transformations, provide a comma-separated list. For example, props=first_name,last_name,email.mask.

    Each string:

    The name of a property or a transformation in the format <property-name>.<transformer-name>.

Request body​

This is a JSON object consisting of maps in which the keys are property names. The in map maps a property name to an array of possible values for that property. The match map maps a property name to the required value for that property. The like map maps a property name to a search pattern that the property value should match. An object matches the query if the object meets the requirements of both maps. For example:

{
  "in": {
    "email": ["john@work.com", "john@home.com"],
  },
  "match": {
    "first_name": "John",
    "last_name": "Doe"
  }
}

is equivalent to:

WHERE first_name = 'John' AND last_name='Doe' AND email IN ('john@work.com', 'john@home.com')

Another example:

{
  "like": {
    "email": "*john*",
  },
  "match": {
    "region": "US"
  }
}

is equivalent to:

WHERE email LIKE '%john%' AND region = 'US'
object required*

A query is a map of operators to match against the properties of an object.

Multiple operators can be combined in a single query.

  • in - object

    The in query operator allows you to match a property value against a list of values.

    Each key in the map is a property name, and the value is a list of values to match.

    The SQL equivalent of this query is:

    SELECT * FROM objects WHERE property1 IN (value1, value2) AND property2 IN (value1, value2);
    Values of additional properties are arrays of any type
    Each item:

    A value to match. Must be of the same type as the property.

  • match - object

    The match query operator allows you to match a property value against a specific value.

    Each key in the map is a property name, and the value is the value to match.

    The SQL equivalent of this query is:

    SELECT * FROM objects WHERE property1 = value1 AND property2 = value2;
    Values of additional properties are any type

    A value to match. Must be of the same type as the property.

  • like - object

    The like query operator allows you to match a property value against a search pattern.

    Each key in the map is a property name, and the value is the pattern to match.

    The SQL equivalent of this query is:

    SELECT * FROM objects WHERE property1 LIKE pattern1 AND property2 LIKE pattern2;
    Values of additional properties are any type

    A pattern to match. Must be of the same type as the property.

Example
{
  "in": {
    "first_name": [
      "Pat"
    ]
  },
  "match": {
    "date_of_birth": "1993-02-22"
  }
}

Possible responses​

The request is successful.

object required*
  • results - array of objects required*

    A page of objects.

    Each object:

    A list of maps of object properties and their values.

    Example
    {
      "date_of_birth": "1993-02-22",
      "email": "patfar@example.com",
      "first_name": "Pat",
      "last_name": "Far",
      "phone_number": "+11011010101"
    }
  • paging - object required*

    Pagination information.

    • size - integer required*

      Number of results in the current page.

    • remaining_count - integer required*

      The remaining number of objects that can be read in ensuing calls to this method.

    • cursor - string required*

      An opaque string you should provide to get the next page.

Example
{
  "results": [
    {
      "date_of_birth": "1993-02-22",
      "email": "patfar@example.com",
      "first_name": "Pat",
      "last_name": "Far",
      "phone_number": "+11011010101"
    }
  ],
  "paging": {
    "size": 0,
    "remaining_count": 0,
    "cursor": "string"
  }
}

Try the API

Authorization

Path parameters

Query parameters

Headers

Request body

Navigate to the docs of your local Vault installation to try the API directly from there.

Code examples

Example