Users Data and Properties¶

List All User-Properties¶

GET users-properties/¶

Note

Authorized Roles: root, manager, backend, frontend

Get all user-properties for the current database.

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
properties (list-of-object) –
All properties
Inner fields
- property_name (string) – [max-length: 64] Property name. Only alphanumeric characters, dots, underscores or hyphens are allowed. The names ‘item_id’ and ‘user_id’ are reserved
- value_type (string) – [max-length: 10] Property type [see Property Types]
- repeated (bool) – Whether the property has many values
- metadata (json-value) – Metadata, unvalidated JSON
- indexed (bool) – Whether the property is indexed for filters

EXAMPLE RESPONSE¶

  {
      "properties": [
          {
              "property_name": "age",
              "value_type": "int8",
              "repeated": false,
              "indexed": true,
              "metadata": {}
          },
          {
              "property_name": "subscriptions",
              "value_type": "unicode32",
              "repeated": true,
              "indexed": false,
              "metadata": {}
          }
      ]
  }

Create New User-Property¶

POST users-properties/¶

Note

Authorized Roles: root, manager, backend

Create a new user-property, identified by property_name (case-insensitive).

Request JSON Object

property_name (string) – [max-length: 64] Property name. Only alphanumeric characters, dots, underscores or hyphens are allowed. The names ‘item_id’ and ‘user_id’ are reserved
value_type (string) – [max-length: 10] Property type [see Property Types]
repeated (bool) – Optional. Whether the property has many values
metadata (json-value) – Optional. Metadata, unvalidated JSON
indexed (bool) – Optional. Whether the property is indexed for filters

EXAMPLE QUERY BODY¶

  {
      "property_name": "age",
      "value_type": "int8",
      "repeated": false,
      "metadata": {"flag": true}
  }

Errors:

DuplicatedError with error name DUPLICATED_USER_PROPERTY if a user property with the same name already exists
WrongData with error name WRONG_DATA_TYPE if value_type is invalid

Get One User-Property¶

GET users-properties/<str:property_name>/¶

Note

Authorized Roles: root, manager, backend

Get one user-property given its property_name.

Response JSON Object

property_name (string) – [max-length: 64] Property name. Only alphanumeric characters, dots, underscores or hyphens are allowed. The names ‘item_id’ and ‘user_id’ are reserved
value_type (string) – [max-length: 10] Property type [see Property Types]
repeated (bool) – Optional. Whether the property has many values
metadata (json-value) – Optional. Metadata, unvalidated JSON
indexed (bool) – Optional. Whether the property is indexed for filters

EXAMPLE RESPONSE¶

  {
      "property_name": "age",
      "value_type": "int8",
      "repeated": false,
      "indexed": false,
      "metadata": {}
  }

Errors:

NotFoundError with error name USER_PROPERTY_NOT_FOUND if the property name cannot be found

Delete User-Property¶

DELETE users-properties/<str:property_name>/¶

Note

Authorized Roles: root, manager, backend

Delete an user-property given by its name

Errors:

NotFoundError with error name USER_PROPERTY_NOT_FOUND if the property name cannot be found

Get Properties of One User¶

GET users/<str:user_id>/properties/¶

Note

Authorized Roles: root, manager, backend

Get property values of one user given its ID.

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
user (object) – User data

EXAMPLE RESPONSE¶

  {
      "user": {
          "user_id": "123e4567-e89b-12d3-a456-426614174000",
          "subscriptions": ["channel1", "channel2"],
          "age": 25
      }
  }

Errors:

NotFoundError with error name USER_NOT_FOUND if no user with the given user_id can be found

Create or Replace Properties of One User¶

PUT users/<str:user_id>/properties/¶

Note

Authorized Roles: root, manager, backend

Create property values for one user, or replace them if the user_id already exists.

All property types need to be defined beforehand, see Items and Users Properties.

Note that user_id cannot be a “null” or “falsy” value, such as empty string or 0.

Request JSON Object

user (object) – User data
wait_for_completion (bool) – Optional. Default is true to wait for completion and respond with 200 OK. Set to false to respond immediately with 202 Accepted after validation, and process asynchronously in the background. The background process may take 30 seconds to start, and there is no way to get notified when the process is complete. No validation of users properties values is done beforehand, the background task may fail silently.

Example:

EXAMPLE QUERY BODY¶

  {
      "user": {
          "subscriptions": ["channel1", "channel2"],
          "age": 25
      }
  }

Errors:

WrongData with error name WRONG_DATA_TYPE if the properties are invalid

Partial Update Properties of One User¶

PATCH users/<str:user_id>/properties/¶

Note

Authorized Roles: root, manager, backend

Partially update some property values of one user. The properties that are not listed in the request body will be left unchanged. The list of values given for repeated properties will replace (not append) the previous list of values.

Use the body parameter create_if_missing to control whether an error should be returned or a new user should be created when the user_id does not already exist.

All property types need to be defined beforehand, see Items and Users Properties.

Note that user_id cannot be a “null” or “falsy” value, such as empty string or 0.

Request JSON Object

user (object) – User data
create_if_missing (bool) – Optional. Create user that does not exist

Example:

EXAMPLE QUERY BODY¶

  {
      "user": {
          "subscriptions": ["channel1", "channel2"],
          "age": 25
      },
      "create_if_missing": false
  }

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
user_created (bool) – Indicates if the user was created
user_modified (bool) – Indicates if the user was modified

EXAMPLE RESPONSE¶

  {
      "user_created": true,
      "user_modified": false
  }

Errors:

WrongData with error name WRONG_DATA_TYPE if the properties are invalid
NotFoundError only when create_if_missing=False with error name USER_NOT_FOUND if no user with the given user_id can be found

Delete Properties of One User¶

DELETE users/<str:user_id>/properties/¶: Note

Authorized Roles: root, manager, backend

Delete property values of one user given its ID. Ratings and interactions are not deleted.

Create or Replace Properties of Many Users in Bulk¶

PUT users-bulk/properties/¶

Note

Authorized Roles: root, manager, backend

Create property values for many users in bulk, or update the ones for which the user_id already exist.

All property types need to be defined beforehand, see Items and Users Properties.

Note that user_id cannot be a “null” or “falsy” value, such as empty string or 0.

Request JSON Object

users (object-array) –
(additional fields may be present) Users values
Inner fields
- user_id (ID) – [see Flexible Identifiers], [max_length: 64] User ID
users_m2m (list-of-object) –
Optional. Users repeated values in array-optimized many-to-many format for binary clients [see Repeated Values]
Inner fields
- name (string) – [max-length: 64] M2M name
- array (object-array) – M2M array
  Inner fields
  
  user_index (uint32) – User index (0-based)
  
  value_id (any) – M2M related object ID
wait_for_completion (bool) – Optional. Default is true to wait for completion and respond with 200 OK. Set to false to respond immediately with 202 Accepted after validation, and process asynchronously in the background. The background process may take 30 seconds to start, and there is no way to get notified when the process is complete. No validation of users properties values is done beforehand, the background task may fail silently.

EXAMPLE QUERY BODY (JSON client)¶

  {
      "users": [
          {
              "user_id": "123e4567-e89b-12d3-a456-426614174000",
              "age": 25,
              "subscriptions": ["channel1", "channel2"]
          },
          {
              "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "age": 32,
              "subscriptions": ["channel1"]
          }
      ]
  }

EXAMPLE QUERY BODY (array-optimized format for binary client)¶

  {
      "users": [
          {
              "user_id": "123e4567-e89b-12d3-a456-426614174000",
              "age": 25
          },
          {
              "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "age": 32
          }
      ],
      "users_m2m": [
          {
              "name": "subscriptions",
              "array": [
                  {"user_index": 0, "value_id": "channel1"},
                  {"user_index": 0, "value_id": "channel2"},
                  {"user_index": 1, "value_id": "channel1"}
              ]
          }
      ]
  }

Note that we represent the arrow-optimized using JSON for reability, but you should use a binary array instead

Errors:

WrongData with error name WRONG_DATA_TYPE if the properties are invalid
DuplicatedError with error name DUPLICATED_USER_ID if a user_id occurs multiple times in the same request

List Properties of All Users in Bulk¶

GET users-bulk/properties/¶

Note

Authorized Roles: root, manager, backend

Get property values of multiple users by page. The response is paginated, you can control the response amount and offset using the query parameters amt and cursor.

Note that the array-optimized format users_m2m for repeated values is used only for binary clients. Otherwise (e.g. JSON client), the repeated values are formatted as lists in each individual users.

Query Parameters

amt (int) – Optional. [max: 500] Maximum amount of users returned, by default is 300
cursor (string) – Optional. Pagination cursor, typically from the next_cursor value from the previous response
properties (list-of-string) – Optional. Names of properties to fetch (by default, all properties are fetched)
filters (list-of-object) –
Optional. Filter on user properties [see Filtering on Item Property]
Inner fields
- property_name (string) – User-property name
- op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, neq, notin] Filter Operator
- value (json-value) – Filter Value

EXAMPLE QUERY PARAMS¶

  ?amt=100&cursor=Q21vU1pHb1FjSEp...

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
users (object-array) –
(additional fields may be present) Users values
Inner fields
- user_id (ID) – [see Flexible Identifiers], [max_length: 64] User ID
users_m2m (list-of-object) –
Users repeated values in array-optimized many-to-many format for binary clients [see Repeated Values]
Inner fields
- name (string) – [max-length: 64] M2M name
- array (object-array) – M2M array
  Inner fields
  
  user_index (uint32) – User index (0-based)
  
  value_id (any) – M2M related object ID
has_next (bool) – Indicates whether or not there are more users to request
next_cursor (string) – Pagination cursor to use in next request to get more users

EXAMPLE RESPONSE (JSON client)¶

  {
      "users": [
          {
              "user_id": "123e4567-e89b-12d3-a456-426614174000",
              "age": 25,
              "subscriptions": ["channel1", "channel2"]
          },
          {
              "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "age": 32,
              "subscriptions": ["channel1"]
          }
      ],
      "has_next": true,
      "next_cursor": "Q21vU1pHb1FjSEp..."
  }

Partial Update Properties of Many Users in Bulk¶

PATCH users-bulk/properties/¶

Note

Authorized Roles: root, manager, backend

Partially update some property values of many users. The properties that are not listed in the request body will be left unchanged. The list of values given for repeated properties will replace (not append) the previous list of values.

Use the body parameter create_if_missing to control whether an error should be returned or new users should be created when the user_id does not already exist.

All property types need to be defined beforehand, see Items and Users Properties.

Note that user_id cannot be a “null” or “falsy” value, such as empty string or 0.

Request JSON Object

users (object-array) –
(additional fields may be present) Users values
Inner fields
- user_id (ID) – [see Flexible Identifiers], [max_length: 64] User ID
users_m2m (list-of-object) –
Optional. Users repeated values in array-optimized many-to-many format for binary clients [see Repeated Values]
Inner fields
- name (string) – [max-length: 64] M2M name
- array (object-array) – M2M array
  Inner fields
  
  user_index (uint32) – User index (0-based)
  
  value_id (any) – M2M related object ID
wait_for_completion (bool) – Optional. Default is true to wait for completion and respond with 200 OK. Set to false to respond immediately with 202 Accepted after validation, and process asynchronously in the background. The background process may take 30 seconds to start, and there is no way to get notified when the process is complete. No validation of users properties values is done beforehand, the background task may fail silently.
create_if_missing (bool) – Optional. Create users that do not exist

EXAMPLE QUERY BODY (JSON client)¶

  {
      "users": [
          {
              "user_id": "123e4567-e89b-12d3-a456-426614174000",
              "age": 25,
              "subscriptions": ["channel1", "channel2"]
          },
          {
              "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "age": 32,
              "subscriptions": ["channel1"]
          }
      ],
      "create_if_missing": false
  }

Errors:

WrongData with error name WRONG_DATA_TYPE if the properties are invalid
DuplicatedError with error name DUPLICATED_USER_ID if a user_id occurs multiple times in the same request
NotFoundError only when create_if_missing=False with error name USER_NOT_FOUND if at least one user with the given user_id cannot be found

Delete Properties of Many Users in Bulk¶

DELETE users-bulk/properties/¶

Note

Authorized Roles: root, manager, backend

Delete property values of many users in bulk. Ratings and interactions are not deleted.

Request JSON Object

users_id (ID-array) – Users IDs

EXAMPLE QUERY BODY¶

  {
      "users_id": [
          "123e4567-e89b-12d3-a456-426614174000",
          "c3391d83-553b-40e7-818e-fcf658ec397d"
      ]
  }

List Properties of Many Users by ID¶

POST users-bulk/properties/list/¶

Note

Authorized Roles: root, manager, backend

Get property values of multiple users given their IDs. Note that the HTTP verb is POST so that users ids can be sent in the body, but the endpoint is stateless as GET.

The users in the response are not aligned with the input. In particular this endpoint does not respond with 404 if any user in missing. Instead, the missing users are simply not present in the response.

Request JSON Object

users_id (ID-array) – Users IDs
properties (list-of-string) – Optional. Names of properties to fetch (by default, all properties are fetched)

EXAMPLE QUERY BODY¶

  {
      "users_id": [
          "123e4567-e89b-12d3-a456-426614174000",
          "c3391d83-553b-40e7-818e-fcf658ec397d"
      ]
  }

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
users (object-array) –
(additional fields may be present) Users values
Inner fields
- user_id (ID) – [see Flexible Identifiers], [max_length: 64] User ID
users_m2m (list-of-object) –
Users repeated values in array-optimized many-to-many format for binary clients [see Repeated Values]
Inner fields
- name (string) – [max-length: 64] M2M name
- array (object-array) – M2M array
  Inner fields
  
  user_index (uint32) – User index (0-based)
  
  value_id (any) – M2M related object ID

EXAMPLE RESPONSE (JSON client)¶

  {
      "users": [
          {
              "user_id": "123e4567-e89b-12d3-a456-426614174000",
              "age": 25,
              "subscriptions": ["channel1", "channel2"]
          },
          {
              "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "age": 32,
              "subscriptions": ["channel1"]
          }
      ]
  }

[Deprecated] Get Properties of One User¶

GET users/<str:user_id>/¶: Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See GET users/<str:user_id>/properties/

[Deprecated] Create or Replace One User¶

PUT users/<str:user_id>/¶: Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See PUT users/<str:user_id>/properties/

[Deprecated] Partial Update One User¶

PATCH users/<str:user_id>/¶: Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See PATCH users/<str:user_id>/properties/

[Deprecated] Delete One User¶

DELETE users/<str:user_id>/¶: Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See DELETE users/<str:user_id>/properties/

[Deprecated] Create or Replace Many Users in Bulk¶

PUT users-bulk/¶: Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See PUT users-bulk/properties/

[Deprecated] List Properties of All Users in Bulk¶

GET users-bulk/¶: Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See GET users-bulk/properties/

[Deprecated] Partial Update Many Users in Bulk¶

PATCH users-bulk/¶: Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See PATCH users-bulk/properties/

[Deprecated] Delete Many Users in Bulk¶

DELETE users-bulk/¶: Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See DELETE users-bulk/properties/

[Deprecated] List Properties of Many Users by ID¶

POST users-bulk/list/¶: Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See POST users-bulk/properties/list/

Users Data and Properties¶

List All User-Properties¶

Create New User-Property¶

Get One User-Property¶

Delete User-Property¶

Delete Everything Related to One User¶

Get Properties of One User¶

Create or Replace Properties of One User¶

Partial Update Properties of One User¶

Delete Properties of One User¶

Create or Replace Properties of Many Users in Bulk¶

List Properties of All Users in Bulk¶

Partial Update Properties of Many Users in Bulk¶

Delete Properties of Many Users in Bulk¶

List Properties of Many Users by ID¶

[Deprecated] Get Properties of One User¶

[Deprecated] Create or Replace One User¶

[Deprecated] Partial Update One User¶

[Deprecated] Delete One User¶

[Deprecated] Create or Replace Many Users in Bulk¶

[Deprecated] List Properties of All Users in Bulk¶

[Deprecated] Partial Update Many Users in Bulk¶

[Deprecated] Delete Many Users in Bulk¶

[Deprecated] List Properties of Many Users by ID¶