Skip to main content

Search objects

Learn how to search for personal data objects​

You can search for objects in a collection and return all or a subset of the found object’s values. You can also request transformations of values, where available.

You can use the unsafe option to get all the values of the objects (though it is not recommended). Using unsafe can be combined with the show_builtins option to include the built-in properties.

Whether your request for object values succeeds depends on the permissions you've been granted as part of the Vault’s identity and access management settings.

Search for objects and return object properties​

Overview​

To search for objects in a collection, you use the CLI search objects or the REST API search objects operation passing the property or properties you want to get and the collection name.

Step-by-step​

Say you have a collection called ‘buyers’ that you created using Create a collection. You want to retrieve ‘name‘ and ‘email‘ for all the buyers in this collection that meet a search requirement. For simplicity, assume that the ‘buyers‘ collection contains only these three objects:

The buyers collection
+-----------------------------+------------+
|            email            |    name    |
+-----------------------------+------------+
| mr.john@somemail.com        | John       |
| john1234@anotheremail.com   | John       |
| mary@someemail.com          | Mary       |
+-----------------------------+------------+

Consider these 3 search requirements.

  1. A "match" requirement: The ‘name‘ should be "John".
  2. An "in" (any of) requirement: The ‘email‘ should be either "mr.john@somemail.com" or "mary@someemail.com".
  3. Both a "match" requirement and an "in" requirement: The ‘name‘ should be "John" and also the ‘email‘ should be either "mr.john@somemail.com" or "mary@someemail.com".

The following sections demonstrate how to implement a query for each of these requirements using the CLI and REST API.

Specifying a "match" requirement​

You can search for the objects with a "match" requirement using the CLI like this:

pvault object query \
      --match name=John \
      --props name,email \
      --collection customers

The --match option limits the results to those buyers whose ‘name‘ is "John". If required, you can specify additional --match flags for other properties to limit the results further.

Alternatively, you can specify the search query in JSON format, using the --query-json flag, like this:

pvault object query \
  --query-json '{
    "match": {
      "name":"John"
    }
  }' \
  --props name,email \
  --collection customers

If required, you can specify values for other properties in the "match" object to limit the results further. For both options, you get a response similar to this:

Displaying 2 results.
+-----------------------------+------------+
|            email            |    name    |
+-----------------------------+------------+
| mr.john@somemail.com        | John       |
| john1234@anotheremail.com   | John       |
+-----------------------------+------------+

The response is paginated. See CLI pagination for more information about working with paginated responses.

You can also use the REST API like this:

curl -s -X POST \
      --url 'http://localhost:8123/api/pvlt/1.0/data/collections/customers/query/objects?props=name,email&reason=AppFunctionality' \
      --header 'Authorization: Bearer pvaultauth' \
      --header 'Content-Type: application/json' \
      --data '{
        "match": {"name":"John"}
      }'

If required, you can specify values for other properties in the "match" object to limit the results further. In this case, you get a response similar to this:

{
  "results": [
    {
      "email": "mr.john@somemail.com",
      "name": "John"
    },
    {
      "email": "john1234@anotheremail.com",
      "name": "John"
    }
  ],
  "paging": {
    "size": 2,
    "remaining_count": 0,
    "cursor": ""
  }
}

The response is paginated. See CLI pagination for more information about working with paginated responses.

Specifying an "in" requirement​

You can search for the objects with an "in" requirement using the CLI like this:

pvault object query \
  --in email=mr.john@somemail.com,mary@someemail.com \
  --props name,email \
  --collection customers

The --in option limits the results to those buyers whose ‘email‘ is either "mr.john@somemail.com" or "mary@someemail.com". If required, you can specify additional --in flags for other properties to limit the results further.

Alternatively, you can specify the search query in JSON format, using the --query-json flag, like this:

pvault object query \
  --query-json '{
    "in": {
      "email":[
         "mr.john@somemail.com",
         "mary@someemail.com"
      ]
    }
  }' \
  --props name,email \
  --collection customers

If required, you can specify values for other properties in the "in" object to limit the results further. For both options, you get a response similar to this:

Displaying 2 results.
+-----------------------------+------------+
|            email            |    name    |
+-----------------------------+------------+
| mr.john@somemail.com        | John       |
| mary@someemail.com          | Mary       |
+-----------------------------+------------+

The response is paginated. See CLI pagination for more information about working with paginated responses.

You can also use the REST API like this:

curl -s -X POST \
  --url 'http://localhost:8123/api/pvlt/1.0/data/collections/customers/query/objects?props=name,email&reason=AppFunctionality' \
  --header 'Authorization: Bearer pvaultauth' \
  --header 'Content-Type: application/json' \
  --data '{
    "in": {
      "email":[
         "mr.john@somemail.com",
         "mary@someemail.com"
      ]
    }
  }'

If required, you can specify values for other properties in the "in" object to limit the results further. In this case, you get a response similar to this:

{
  "results": [
    {
      "email": "mr.john@somemail.com",
      "name": "John"
    },
    {
      "email": "mary@someemail.com",
      "name": "Mary"
    }
  ],
  "paging": {
    "size": 2,
    "remaining_count": 0,
    "cursor": ""
  }
}

The response is paginated. See CLI pagination for more information about working with paginated responses.

Specifying a "match" and an "in" requirement​

You can search for the objects with both a "match" and an "in" requirement using the CLI like this:

pvault object query \
  --match name=John \
  --in email=mr.john@somemail.com,john1234@anotheremail.com \
  --props name,email \
  --collection customers

If required, you can specify additional --in and --match flags for other properties to limit the results further.

Alternatively, you can specify the search query in JSON format, using the --query-json flag, like this:

pvault object query \
  --props name,email \
  --collection customers \
  --query-json '{
    "match": {
      "name":"John"
    },
    "in": {
      "email":[
         "mr.john@somemail.com",
         "mary@some.com"
      ]
    }
  }'

If required, you can specify values for other properties in the "in" and "match" objects to limit the results further. For both commands, you get a response similar to this:

Displaying 2 results.
+-----------------------------+------------+
|            email            |    name    |
+-----------------------------+------------+
| mr.john@somemail.com        | John       |
| john1234@anotheremail.com   | John       |
+-----------------------------+------------+

The response is paginated. See CLI pagination for more information about working with paginated responses.

You can also use the REST API like this:

curl -s -X POST \
  --url 'http://localhost:8123/api/pvlt/1.0/data/collections/customers/query/objects?props=name,email&reason=AppFunctionality' \
  --header 'Authorization: Bearer pvaultauth' \
  --header 'Content-Type: application/json' \
  --data '{
    "match": {
      "name":"John"
    },
    "in": {
      "email":[
         "mr.john@somemail.com",
         "john1234@anotheremail.com"
      ]
    }
  }'

If required, you can specify values for other properties in the "in" and "match" objects to limit the results further. In this case, you get a response similar to this:

{
  "results": [
    {
      "email": "john1234@anotheremail.com",
      "name": "John"
    }
  ],
  "paging": {
    "size": 1,
    "remaining_count": 0,
    "cursor": ""
  }
}

The response is paginated. See CLI pagination for more information about working with paginated responses.

Search for objects and return transformed properties​

Overview​

Data types can have transformations. Vault provides several built-in transformations. For example, there is a transformation for the email data type that returns a masked email address similar to this ‘j**********@gmail.com’.

To get transformed values of objects you search for you:

  1. Determine which transformed property values you want from each object.
  2. Use CLI search objects or the REST API search objects operation passing the IDs of the objects, the transformed properties, and collection name.
note

Search queries only support exact matches. Support for other search options is coming soon 🎁.

Step-by-step​

You want to return the name and transformed email address for all buyers with the name "John" in the ‘buyers’ collection you created in Create a collection.

First, build your search query, for example, like this:

name=John
note

See the step-by-step guide in Search for objects and return object properties for more information on creating search queries.

Now, you determine the name of the transformation for email values.

Once you've determined the transformation name for the object property you want to retrieve, define the transformed property by appending the mask name to the property name using dot notation. For example, use email.mask for your transformed email address.

You now search for your buyers and retrieve the values and transformed values using the CLI like this:

pvault object query \
      --match name=John \
      --props name,email.mask \
      --collection customers

You get a response similar to this:

Displaying 2 results.
+-----------------------------+------------+
|          email.mask         |    name    |
+-----------------------------+------------+
| m******@somemail.com        | John       |
| j*******@anotheremail.com   | John       |
+-----------------------------+------------+

The response is paginated. See CLI pagination for more information about working with paginated responses.

Or using the REST API like this:

curl -s -X POST \
      --url 'http://localhost:8123/api/pvlt/1.0/data/collections/customers/query/objects?props=name,email.mask&reason=AppFunctionality' \
      --header 'Authorization: Bearer pvaultauth' \
      --header 'Content-Type: application/json' \
      --data '{
        "match": {"name":"John"}
      }'

You get a response similar to this:

{
  "results": [
    {
      "email": "m*******@somemail.com",
      "name": "John"
    },
    {
      "email": "j*******@anotheremail.com",
      "name": "John"
    }
  ],
  "paging": {
    "size": 2,
    "remaining_count": 0,
    "cursor": ""
  }
}

The response is paginated. See API pagination for more information about working with paginated responses.

On this page