Update a collection

Learn how to update a collection

As the requirements of the apps your Vault serves evolve, you may need to change collections to store new properties, remove properties that are no longer needed, or update properties' attributes.

Updating a collection schema is potentially dangerous. You need to plan your changes to maintain the integrity of the data in your collections and determine how dependent applications and services handle the changes.

To add and update collection properties, Vault provides:

1. Update collection operation and command to add and update properties in a collection.
2. Add collection property operation and command to add properties to a collection.
3. Update collection property operation and command to update a property in a collection.

Only the description, is_index, and is_nullable property attributes can be updated, and you can only change is_nullable from false to true. These are the updates Vault can make without reference to the data stored in a collection. For example, if Vault wanted to change is_nullable from true to false, the operation must confirm that every object in the collection has a value for the changed property. If any object has a null value in the property, the operation is unable to complete until a value is provided.

Add and update collection properties

Where you want to change several collection properties, add collection properties, or both, use the CLI update collection command or REST API update collection operation.

note

The CLI also includes the apply collection command. This command has the same structure and operation as update collection except that it adds a collection if the one specified in the request doesn’t exist.

You can only update the description, is_nullable, and is_indexed attributes of a property. You can only change is_nullable from false to true.

You cannot remove properties from a collection using these features. See Delete a property instead.

Overview

To add or update properties in a collection, you:

1. Define a schema for the updates or additions as a PVSchema or JSON file.
2. Use the CLI update collection command or REST API update collection operation to add and update properties in a collection.

Step-by-step

Step 1 – Design the collection schema

Before updating a collection, decide what properties to update or add to it.

Say you want to change the email property in the buyers collection (see Create a collection for more information) so it's indexed and add a home phone number property. You can define these changes in a PVSchema like this:

buyers PERSONS (
  email EMAIL UNIQUE INDEX,
  home_phone PHONE_NUMBER NULL
);

or JSON format, like this:

{
  "type": "PERSONS",
  "name": "buyers",
  "properties": [
    {
      "name": "email",
      "data_type_name": "EMAIL",
      "is_unique": true,
      "is_index": true
    },
    {
      "name": "home_number",
      "data_type_name": "PHONE_NUMBER",
      "is_nullable": true
    }
  ]
}

Step 2 - Update the collection

After you’ve defined the collection schema, you update the collection using the REST API or CLI.

To update the buyers collection with the CLI using the PVSchema, you use this command:

pvault collection update \
--collection buyers \
--collection-pvschema "
buyers PERSONS (
  email EMAIL UNIQUE INDEX,
  home_phone PHONE_NUMBER NULL
);"

You get a response similar to this:

buyers PERSONS (
  address ADDRESS,
  email EMAIL UNIQUE INDEX,
  home_phone PHONE_NUMBER NULL,
  name NAME,
  phone_number PHONE_NUMBER NULL
);

Similarly, you can update the collection with the REST API, this time using JSON, like this:

curl --request PATCH \
  --silent \
  --url "http://localhost:8123/api/pvlt/1.0/ctl/collections/buyers?format=json" \
  --header 'Authorization: Bearer pvaultauth' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "PERSONS",
  "name": "buyers",
  "properties": [
    {
      "name": "email",
      "data_type_name": "EMAIL",
      "is_unique": true,
      "is_index": true
    },
    {
      "name": "home_number",
      "data_type_name": "PHONE_NUMBER",
      "is_nullable": true
    }
  ]
}'

Add, update, or delete a collection property

Overview

You can make changes to individual collection properties using the collection property:

• Add CLI command or REST API operation.
• Update CLI command or REST API operation.
• Delete CLI command or REST API operation.

This group of functions also includes the:

• List collection properties CLI command and REST API operation that provide details of property settings for all properties in a collection.
• Get collection property CLI command and REST API operation that provide details of the settings for a property.

The limitations on updating properties seen in the collection operations and commands also apply here: you can only update the description, is_nullable, and is_indexed attributes and change is_nullable from false to true. However, these functions provide the ability to delete a property.

Get a property

To get a property’s details from a collection, you:

1. Determine which property you want to retrieve, including the name of the collection it is in.
2. Use the CLI get collection property command or REST API get collection property operation, passing the collection and property names.

Step-by-step

Say you want to retrieve the email property's details from the buyers collection you created in Create a collection.

You retrieve the object values using the CLI like this:

pvault collection property get --collection buyers --name email

You get a response similar to this:

+-------------------------------+----------------+-------------+------------+--------------+----------+-------------+-------------+-----------+-------------------------------+-------+
|         creation_time         | data_type_name | description | is_builtin | is_encrypted | is_index | is_nullable | is_readonly | is_unique |       modification_time       | name  |
+-------------------------------+----------------+-------------+------------+--------------+----------+-------------+-------------+-----------+-------------------------------+-------+
| Sat, 08 Jul 2023 17:20:52 UTC | EMAIL          |             | false      | true         | true     | false       | false       | true      | Sat, 08 Jul 2023 17:22:57 UTC | email |
+-------------------------------+----------------+-------------+------------+--------------+----------+-------------+-------------+-----------+-------------------------------+-------+

You can also use the --json flag to return this information in JSON format. The add and update CLI commands can ingest JSON, so this format may be useful depending on your needs.

Or using the REST API like this:

curl --request GET \
  --silent \
  --url "http://localhost:8123/api/pvlt/1.0/ctl/collections/buyers/properties/email" \
  --header 'Authorization: Bearer pvaultauth'

You get a response similar to this:

{
  "description": "",
  "name": "email",
  "data_type_name": "EMAIL",
  "is_unique": true,
  "is_index": true,
  "is_encrypted": true,
  "is_nullable": false,
  "is_builtin": false,
  "is_readonly": false,
  "creation_time": "2022-07-16T16:28:37.182702796Z",
  "modification_time": "2022-07-16T16:28:37.182702796Z"
}

Add a property

To add a property to a collection, you:

1. Determine the attributes of the property you want to add and the name of the collection to add it to.
2. Use the CLI add collection property command or REST API add collection property operation, passing the collection and property name and attributes.

Step-by-step

Say you want to add a date_of_birth property to the buyers collection. Using the CLI, you can choose between providing a JSON specification or using CLI flags to define the property.

You add the property using the CLI flags like this:

pvault collection property add \
  --collection buyers \
  --name date_of_birth \
  --description "Date of birth" \
  --pii-type-name DATE_OF_BIRTH \
  --is-nullable

You get a response similar to this:

+-------------------------------+----------------+---------------+------------+--------------+----------+-------------+-------------+-----------+-------------------------------+-----------------+
|         creation_time         | data_type_name |  description  | is_builtin | is_encrypted | is_index | is_nullable | is_readonly | is_unique |       modification_time       |      name       |
+-------------------------------+----------------+---------------+------------+--------------+----------+-------------+-------------+-----------+-------------------------------+-----------------+
| Sat, 21 Oct 2023 17:09:32 UTC | DATE_OF_BIRTH  | Date of birth | false      | true         | false    | true        | false       | false     | Sat, 21 Oct 2023 17:09:32 UTC | date_of_birth   |
+-------------------------------+----------------+---------------+------------+--------------+----------+-------------+-------------+-----------+-------------------------------+-----------------+

You can also use the --json flag to return this information in JSON format.

Or you use the REST API, which only accepts a JSON specification, like this:

curl --request POST \
  --silent \
  --url "http://localhost:8123/api/pvlt/1.0/ctl/collections/buyers/properties/date_of_birth" \
  --header 'Authorization: Bearer pvaultauth' \
  --header 'Content-Type: application/json' \
  --data '{
  "description": "Date of birth",
  "name": "date_of_birth",
  "data_type_name": "DATE_OF_BIRTH",
  "is_unique": false,
  "is_index": false,
  "is_encrypted": true,
  "is_nullable": true
}'

You get a response similar to this:

{
  "description": "Date of birth",
  "name": "date_of_birth",
  "data_type_name": "DATE_OF_BIRTH",
  "is_unique": false,
  "is_index": false,
  "is_encrypted": true,
  "is_nullable": true,
  "is_builtin": false,
  "is_readonly": false,
  "creation_time": "2022-07-16T16:28:37.182702796Z",
  "modification_time": "2022-07-16T16:28:37.182702796Z"
}

Update a property

To update a property in a collection, you:

1. Determine the attributes of the property you want to update and the name of the collection it is in. Remember that updates to a property are limited to its description, is_index, and is_nullable attributes. You can only change is_nullable from false to true.
2. Use the CLI update collection property command or REST API update collection property operation, passing the collection, the property names, and details of the attributes to update.

Step-by-step

Say you want to change the description of the date_of_birth property in the buyers collection from “Date of birth” to “Birthday”. Using the CLI, you can choose between providing a JSON specification or using CLI flags to define the property.

You update the property using the CLI flags like this:

pvault collection property update \
  --collection buyers \
  --name date_of_birth \
  --description "Birthday"

You get a response similar to this:

+-------------------------------+----------------+-------------+------------+--------------+----------+-------------+-------------+-----------+-------------------------------+-----------------+
|         creation_time         | data_type_name | description | is_builtin | is_encrypted | is_index | is_nullable | is_readonly | is_unique |       modification_time       |      name       |
+-------------------------------+----------------+-------------+------------+--------------+----------+-------------+-------------+-----------+-------------------------------+-----------------+
| Sat, 21 Oct 2023 17:09:32 UTC | DATE_OF_BIRTH  | Birthday    | false      | true         | false    | true        | false       | false     | Tue, 31 Oct 2023 02:12:23 UTC | date_of_birth   |
+-------------------------------+----------------+-------------+------------+--------------+----------+-------------+-------------+-----------+-------------------------------+-----------------+

You can also use the --json flag to return this information in JSON format.

Or you use the REST API, which only accepts a JSON specification, like this:

curl --request PATCH \
  --silent \
  --url "http://localhost:8123/api/pvlt/1.0/ctl/collections/buyers/properties/date_of_birth" \
  --header 'Authorization: Bearer pvaultauth' \
  --header 'Content-Type: application/json' \
  --data '{ "description": "Birthday" }'

You get a response similar to this:

{
  "description": "Birthday",
  "name": "date_of_birth",
  "data_type_name": "DATE_OF_BIRTH",
  "is_unique": false,
  "is_index": false,
  "is_encrypted": true,
  "is_nullable": true,
  "is_builtin": false,
  "is_readonly": false,
  "creation_time": "2023-10-21T17:17:18.952671Z",
  "modification_time": "2023-10-31T02:40:18.189319Z"
}

Delete a property

To delete a property in a collection, you:

1. Determine the name of the property you want to delete and the name of the collection it is in.
2. Use the CLI delete collection property command or REST API delete collection property operation, passing the collection and property name.

Step-by-step

Say you want to delete the date_of_birth property from the buyers collection.

You delete the property using the CLI like this:

pvault collection property delete \
  --collection buyers \
  --name date_of_birth

You get a response similar to this:

INF Command completed successfully

Or you use the REST API like this:

curl --request DELETE \
  --silent \
  --url "http://localhost:8123/api/pvlt/1.0/ctl/collections/buyers/properties/date_of_birth" \
  --header 'Authorization: Bearer pvaultauth' \
  --header 'Content-Type: application/json'

You get a Status 200 OK response to confirm that Vault deleted the property.