Skip to main content

Update collection

patch
/api/pvlt/1.0/ctl/collections/{collection}

Updates properties of a collection.

The update includes:

  • Adding any properties in the request that are not in the collection.
  • Amending the description, is_unique, is_index, is_substring_index, and is_nullable attributes, where they have changed, for any properties in the request that are in the collection.
    • is_nullable can only be changed from false to true.
    • is_unique can only be changed from true to false.
    • is_substring_index can only be changed from true to false.
    • All other property attributes are ignored.
note

The combined length of the collection name and the longest property name can not exceed 40 characters.

The collection request can be provided in JSON or PVSchema format by setting the Content-Type header to application/json or application/pvschema, respectively. The collection can be returned in JSON or PVSchema format using the format query parameter or by setting the Accept header to application/json or application/pvschema, respectively. The default is to return JSON.

See PVSchema for more details on the structure and content of PVSchema.

The collection name provided in the path parameter must match the collection name in the JSON or PVSchema.

The response contains the collection with all the properties.

info

This command may take a while to complete (e.g. when adding an index) and is excluded from Vault's standard call timeout.

The role that performs this operation must have the CapCollectionsWriter capability. See Access control for more information about how capabilities are used to control access to operations.

Request

Path parameters

  • collection - string required*

    The name of a collection.

Query parameters

  • format - string

    The format of the response. Overrides any Accept header value provided.

  • options - array of strings

    Options for the operation. Options include:

    • show_builtins – show built-in properties in the response.
    Each string:

Request body

Details of the collection, including its properties.

object required*
  • creation_time - string

    The time when the collection was created, in RFC3339Nano format. Vault sets this value automatically. Sending a value for this field is ignored.

  • modification_time - string

    The time when the collection was last modified, in RFC3339Nano format. Vault sets this value automatically. Sending a value for this field is ignored.

  • name - string required*

    The name of a collection.

  • properties - array of objects required*
    Each object:
    • creation_time - string

      The time when the property was created, in RFC3339Nano format. Vault sets this value automatically. Sending a value for this field is ignored.

    • modification_time - string

      The time when the property was last modified, in RFC3339 format. Vault sets this value automatically. Sending a value for this field is ignored.

    • description - string

      The description of a model.

    • is_builtin - boolean

      Whether the property is created by Vault (or by the user). Built-in properties cannot be deleted or modified. Sending a value for this field is ignored.

    • is_encrypted - boolean

      Whether the value is stored encrypted.

    • is_index - boolean

      Whether the backend storage is optimized for searches on this property. Cannot be set to true for properties with data types LONG_TEXT, JSON, or BLOB, or custom data types based on those types.

    • is_substring_index - boolean

      Whether the backend storage is optimized for substring searches on this property.

    • is_nullable - boolean

      Whether the value of the property can be removed (set to null).

    • is_readonly - boolean

      Whether the user can modify values of this property. Ignored for user define properties. Sending a value for this field is ignored.

    • is_unique - boolean

      Whether the backend storage enforces unique values for active objects. Cannot be set to true for properties with data types LONG_TEXT, JSON, or BLOB, or custom data types based on those types.

    • name - string required*

      The name of a property.

    • data_type_name - string required*

      The name of a data type.

  • type - string required*

    The schema prototype the collection is based on.

Example
{
"type": "PERSONS",
"name": "customers",
"properties": [
{
"description": "Date of birth",
"name": "date_of_birth",
"data_type_name": "DATE_OF_BIRTH",
"is_nullable": true
},
{
"description": "Email",
"name": "email",
"data_type_name": "EMAIL",
"is_unique": true,
"is_index": true,
"is_substring_index": false,
"is_nullable": true
},
{
"description": "First name",
"name": "first_name",
"data_type_name": "NAME"
},
{
"description": "Last name",
"name": "last_name",
"data_type_name": "NAME"
},
{
"description": "Phone number",
"name": "phone_number",
"data_type_name": "PHONE_NUMBER",
"is_unique": true,
"is_index": true,
"is_substring_index": false,
"is_nullable": true
}
]
}
Example
{
"type": "PERSONS",
"name": "customers",
"properties": [
{
"description": "Social Security Number",
"name": "ssn",
"data_type_name": "SSN",
"is_unique": true,
"is_index": true,
"is_substring_index": false,
"is_encrypted": true,
"is_nullable": true,
"is_builtin": false,
"is_readonly": false,
"creation_time": "2023-01-25T17:31:40.291033Z",
"modification_time": "2023-01-25T17:31:40.291033Z"
}
],
"creation_time": "2023-01-25T16:21:48.308234Z",
"modification_time": "2023-01-25T16:21:48.308234Z"
}

Possible responses

The request is successful.

object required*
  • creation_time - string

    The time when the collection was created, in RFC3339Nano format. Vault sets this value automatically. Sending a value for this field is ignored.

  • modification_time - string

    The time when the collection was last modified, in RFC3339Nano format. Vault sets this value automatically. Sending a value for this field is ignored.

  • name - string required*

    The name of a collection.

  • properties - array of objects required*
    Each object:
    • creation_time - string

      The time when the property was created, in RFC3339Nano format. Vault sets this value automatically. Sending a value for this field is ignored.

    • modification_time - string

      The time when the property was last modified, in RFC3339 format. Vault sets this value automatically. Sending a value for this field is ignored.

    • description - string

      The description of a model.

    • is_builtin - boolean

      Whether the property is created by Vault (or by the user). Built-in properties cannot be deleted or modified. Sending a value for this field is ignored.

    • is_encrypted - boolean

      Whether the value is stored encrypted.

    • is_index - boolean

      Whether the backend storage is optimized for searches on this property. Cannot be set to true for properties with data types LONG_TEXT, JSON, or BLOB, or custom data types based on those types.

    • is_substring_index - boolean

      Whether the backend storage is optimized for substring searches on this property.

    • is_nullable - boolean

      Whether the value of the property can be removed (set to null).

    • is_readonly - boolean

      Whether the user can modify values of this property. Ignored for user define properties. Sending a value for this field is ignored.

    • is_unique - boolean

      Whether the backend storage enforces unique values for active objects. Cannot be set to true for properties with data types LONG_TEXT, JSON, or BLOB, or custom data types based on those types.

    • name - string required*

      The name of a property.

    • data_type_name - string required*

      The name of a data type.

  • type - string required*

    The schema prototype the collection is based on.

Example
{
"type": "PERSONS",
"name": "customers",
"properties": [
{
"description": "Date of birth",
"name": "date_of_birth",
"data_type_name": "DATE_OF_BIRTH",
"is_nullable": true
},
{
"description": "Email",
"name": "email",
"data_type_name": "EMAIL",
"is_unique": true,
"is_index": true,
"is_substring_index": false,
"is_nullable": true
},
{
"description": "First name",
"name": "first_name",
"data_type_name": "NAME"
},
{
"description": "Last name",
"name": "last_name",
"data_type_name": "NAME"
},
{
"description": "Phone number",
"name": "phone_number",
"data_type_name": "PHONE_NUMBER",
"is_unique": true,
"is_index": true,
"is_substring_index": false,
"is_nullable": true
}
]
}
Example
{
"type": "PERSONS",
"name": "customers",
"properties": [
{
"description": "Social Security Number",
"name": "ssn",
"data_type_name": "ssn",
"is_unique": true,
"is_index": true,
"is_substring_index": false,
"is_encrypted": true,
"is_nullable": true,
"is_builtin": false,
"is_readonly": false,
"creation_time": "2022-12-01T10:20:47.115228Z",
"modification_time": "2022-12-01T10:20:47.115228Z"
}
],
"creation_time": "2022-12-01T09:45:03.015895Z",
"modification_time": "2022-12-01T09:45:03.015895Z"
}

Try the API

Authorization

Path parameters

Query parameters

Request body

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

Code examples

Example