Create a collection

Learn how to create a collection

Personal and sensitive data is stored in the Vault using collections. There are two types of collections you can create:

1. PERSONS – collections of data that describe people. For example, customers, employees, users, teachers, students, patients, etc.
2. DATA – collections that describe sensitive private resources owned by a person in a one-to-one or one-to-many relationship. For example, workplace data and information about education, bank information, credit cards, health-related information, etc.

See the schema prototypes reference for more information about the content of these collection types and how to establish relationships between the objects they contain.

Create a PERSONS collection

Overview

To create a collection you:

1. Define the collection schema as a PVSchema or JSON file.
2. Use the CLI add collection command or REST API add collection operation, passing the PVSchema or JSON file.

Step-by-step

Step 1 – Design the collection schema

Before creating a collection, you should decide what properties to store in it.

Say you want to build a system to store the private information for an e-commerce app. You have seller and buyer data you want to store. Also, you have buyers’ payment information, which a buyer owns. To support the system, you create sellers and buyers PERSONS collections.

For the buyers collection, you identify the private information to store for each buyer. For example, each buyer has a name, email, address, and optional phone number. You also want to verify that emails are unique for each buyer and be able to perform substring searches on the buyer's name.

warning

After creating a collection you cannot modify a property's data type or whether it is encrypted. You are also limited making a property nullable, not unique, and turning off substring indexing. You can freely change a property's description and whether it's index for string searches. You cannot modify the settings for built-in properties.

After identifying the information, you define it in a PVSchema, like this:

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

or JSON format, like this:

{
  "type": "PERSONS",
  "name": "buyers",
  "properties": [
    {
      "name": "name",
      "data_type_name": "NAME",
      "is_substring_index": true
    },
    {
      "name": "address",
      "data_type_name": "ADDRESS"
    },
    {
      "name": "email",
      "data_type_name": "EMAIL",
      "is_unique": true
    },
    {
      "name": "phone_number",
      "data_type_name": "PHONE_NUMBER",
      "is_nullable": true
    }
  ]
}

note

When possible, use the semantic data types provided by Vault. In this example, you could define each property of the buyer as a STRING. Defining the properties with the semantic data types NAME, EMAIL, and PHONE_NUMBER means you can apply transformations and use other Vault features that handle scenarios for various data types.

Step 2 - Create the collection

Once you have defined the collection schema, you create the collection using the REST API or CLI.

To create the buyers collection with the CLI you use this command:

pvault collection add --collection-pvschema "
buyers PERSONS (
  address ADDRESS,
  email EMAIL UNIQUE,
  name NAME SUBSTRING_INDEX,
  phone_number PHONE_NUMBER NULL
);"

You get a response similar to this:

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

Similarly, you can create the collection with the REST API like this:

curl --request POST \
  --silent \
  --url "http://localhost:8123/api/pvlt/1.0/ctl/collections?reason=AppFunctionality" \
  --header 'Authorization: Bearer pvaultauth' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "PERSONS",
  "name": "buyers",
  "properties": [
    {
      "name": "name",
      "data_type_name": "NAME",
      "is_substring_index": true
    },
    {
      "name": "address",
      "data_type_name": "ADDRESS"
    },
    {
      "name": "email",
      "data_type_name": "EMAIL",
      "is_unique": true
    },
    {
      "name": "phone_number",
      "data_type_name": "PHONE_NUMBER",
      "is_nullable": true
    }
  ]
}'

Create a DATA collection

Overview

Similar to a PERSONS collection, the steps you take to create a DATA collection are:

1. Define the collection schema as a PVSchema or JSON file.
2. Use the CLI add collection command or REST API add collection operation, passing the PVSchema or JSON file.

Step-by-step

Step 1 – Design the collection schema

Before creating the collection, you should decide on what properties to store in it.

In your e-commerce app, there is buyers’ payment method information that a buyer owns. You create the credit_cards DATA collection to store the information

The payment method information defines credit card details including card number, holder name, expiration date, and a CVV.

After identifying the information, you define it in a PVSchema, like this:

credit_cards DATA (
  cvv CC_CVV,
  expiration CC_EXPIRATION_STRING,
  holder_name CC_HOLDER_NAME,
  number CC_NUMBER
);

or in JSON format, like this:

{
  "type": "DATA",
  "name": "credit_cards",
  "properties": [
    {
      "name": "cvv",
      "data_type_name": "CC_CVV"
    },
    {
      "name": "expiration",
      "data_type_name": "CC_EXPIRATION_STRING"
    },
    {
      "name": "holder_name",
      "data_type_name": "CC_HOLDER_NAME"
    },
    {
      "name": "number",
      "data_type_name": "CC_NUMBER"
    }
  ]
}

Step 2 – Create the collection

When you have defined the collection schema, you create the collection using the REST API or CLI.

To create the credit_cards collection with the CLI you use this command:

pvault collection add --collection-pvschema "
credit_cards DATA (
  cvv CC_CVV,
  expiration CC_EXPIRATION_STRING,
  holder_name CC_HOLDER_NAME,
  number CC_NUMBER
);"

You get a response similar to this:

credit_cards DATA (
  cvv CC_CVV,
  expiration CC_EXPIRATION_STRING,
  holder_name CC_HOLDER_NAME,
  number CC_NUMBER
);

Similarly, you can create the collection with the REST API, like this:

curl --request POST \
  --silent \
  --url "http://localhost:8123/api/pvlt/1.0/ctl/collections?reason=AppFunctionality" \
  --header 'Authorization: Bearer pvaultauth' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "DATA",
  "name": "credit_cards",
  "properties": [
    {
      "name": "cvv",
      "data_type_name": "CC_CVV"
    },
    {
      "name": "expiration",
      "data_type_name": "CC_EXPIRATION_STRING"
    },
    {
      "name": "holder_name",
      "data_type_name": "CC_HOLDER_NAME"
    },
    {
      "name": "number",
      "data_type_name": "CC_NUMBER"
    }
  ]
}'