User Properties

User properties definition

User properties are used for modeling users. The following methods allow the definition of user properties. The properties may be thought of as columns in a relational database table.

put

Add User Property

Adding a user property is somewhat equivalent to adding a column to the table of users. The users may be characterized by various properties of different types.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.AddUserProperty(propertyName, type, {
  // optional parameters:
  role: 'title',  // string / Object
  metadata: [],   // array
}));

Since version

1.3.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 1.3.0

ID of your database.

propertyName

String

Located in: path

Required: Yes

Since version: 1.3.0

Name of the user property to be created. Currently, the following names are reserved: id, userid, case-insensitively. Also, the length of the property name must not exceed 63 characters.

type

String

Located in: body

Required: Yes

Value type of the user property to be created. One of: int, double, string, boolean, timestamp, set.

int - Signed integer number.
double - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).
string - UTF-8 string.
boolean - true / false
timestamp - Value representing date and time. ISO8601-1 pattern (string) or UTC epoch time (number).
set - Set of strings.

role

String

Object

Located in: body

Required: No

Role to assign to the property.

metadata

Array

Located in: body

Required: No

List of metadata entries to assign to the property.

Responses

201

Successful operation.

400

Property name does not match ^[a-zA-Z0-9_-:]+$, or it is a reserved keyword (''id'', ''userid''), or its length exceeds 63 characters. Type information is missing, or the given type is invalid.

409

Property of the given name is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Delete User Property

Deleting a user property is roughly equivalent to removing a column from the table of users.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.DeleteUserProperty(propertyName));

Since version

1.3.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 1.3.0

ID of your database.

propertyName

String

Located in: path

Required: Yes

Since version: 1.3.0

Name of the property to be deleted.

Responses

200

Successful operation.

400

Property name does not match ^[a-zA-Z0-9_-:]+$.

404

Property of the given name is not present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the user property was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.

get

Get User Property Info

Gets information about specified user property.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.GetUserPropertyInfo(propertyName));

Since version

1.3.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 1.3.0

ID of your database.

propertyName

String

Located in: path

Required: Yes

Since version: 1.3.0

Name of the property about which the information is to be retrieved.

Responses

200

Successful operation.

{
  "name": "country",
  "type": "string"
}

400

Property name does not match ^[a-zA-Z0-9_-:]+$.

404

Property of the given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List User Properties

Gets the list of all the user properties in your database.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListUserProperties());

Since version

1.3.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 1.3.0

ID of your database.

Responses

200

Successful operation.

[
  {
    "name": "country",
    "type": "string"
  },
  {
    "name": "sex",
    "type": "string"
  }
]

404

Invalid URL.

Values of user properties

The following methods allow assigning property values to the user. Set values are examined by content-based algorithms and used in building recommendations, especially for users that have only a few interactions (e.g., new users). Useful properties may be, for example, gender or region. The values can be used in filtering using the context_user ReQL function.

post

Set User Values

Sets/updates (some) property values of the given user. The properties (columns) must be previously created by Add user property.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.SetUserValues(userId, values, {
  // optional parameters:
  cascadeCreate: true,  // boolean
}));

Since version

1.3.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 1.3.0

ID of your database.

userId

String

Located in: path

Required: Yes

Since version: 1.3.0

ID of the user which will be modified.

Object

Located in: body

Required: Yes

Since version: 1.3.0

The values for the individual properties.

Example of the body:

  {
    "country": "US",
    "sex": "F"
  }

Set user values can also cascade create the user if it's not already present in the database.

For this functionality:

When using the client libraries: Set the optional cascadeCreate parameter to true, just like when creating an interaction.
When using directly REST API: Set special "property" !cascadeCreate.

Example:
```
  {
    "country": "US",
    "!cascadeCreate": true
  }
```
Note the exclamation mark (!) at the beginning of the parameter's name to distinguish it from item property names.

Responses

200

Successful operation.

400

Property name does not match ''^[a-zA-Z0-9_-:]+$'', value does not agree to property type.

404

Property of the given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

Get User Values

Gets all the current property values of the given user.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.GetUserValues(userId));

Since version

1.3.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 1.3.0

ID of your database.

userId

String

Located in: path

Required: Yes

Since version: 1.3.0

ID of the user whose properties are to be obtained.

Responses

200

Successful operation.

{
  "country": "US",
  "sex": "F"
}

400

The userId does not match ^[a-zA-Z0-9_-:@.]+$

404

User of the given userId is not present in the catalog. If there is no additional info in the JSON response, you probably have an error in your URL.

docs.recombee.com