Recombee Docs
Visit recombee.comStart Free

Item Properties

Item properties are used for modeling your domain. The following methods allow the definition of item properties. The properties may be thought of as columns in a relational database table.

put

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

Node.jsPythonRubyJavaPHPC#GoREST
Copy
Initialization
client.send(new requests.AddItemProperty(propertyName, type, {
  // optional parameters:
  role: 'title',  // string / Object
  metadata: [],   // array
}));
databaseId
String
Located in: path
Required: Yes

ID of your database.

propertyName
String
Located in: path
Required: Yes

Name of the item property to be created. Currently, the following names are reserved: id, itemid, 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 item property to be created. One of: int, double, string, boolean, timestamp, set, image or imageList.

  • 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.

  • image - URL of an image (jpeg, png or gif).

  • imageList - List of URLs that refer to images.

role
String
Object
Located in: body
Required: No
Since version: 6.3.0

Role to assign to the property.

metadata
Array
Located in: body
Required: No
Since version: 6.3.0

List of metadata entries to assign to the property.

201

Successful operation.

400

Property name does not match ^[a-zA-Z0-9_-:]+$, or it is a reserved keyword (''id'', ''itemid''), 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

Deleting an item property is roughly equivalent to removing a column from the table of items.

Node.jsPythonRubyJavaPHPC#GoREST
Copy
Initialization
client.send(new requests.DeleteItemProperty(propertyName));
databaseId
String
Located in: path
Required: Yes

ID of your database.

propertyName
String
Located in: path
Required: Yes

Name of the property to be deleted.

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 item property was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.

get

Gets information about specified item property.

Node.jsPythonRubyJavaPHPC#GoREST
Copy
Initialization
const result = await client.send(new requests.GetItemPropertyInfo(propertyName));
databaseId
String
Located in: path
Required: Yes

ID of your database.

propertyName
String
Located in: path
Required: Yes

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

200

Successful operation.

{
  "name": "num-processors",
  "type": "int"
}
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

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

Node.jsPythonRubyJavaPHPC#GoREST
Copy
Initialization
const result = await client.send(new requests.ListItemProperties());
databaseId
String
Located in: path
Required: Yes

ID of your database.

200

Successful operation.

[
  {
    "name": "tags",
    "type": "set"
  },
  {
    "name": "release-date",
    "type": "timestamp"
  },
  {
    "name": "description",
    "type": "string"
  }
]
404

Invalid URL.

The following methods allow assigning property values to items in the catalog. Set values are examined by content-based algorithms and used for recommendations, especially in the case of cold-start items that have no interactions yet. Properties are also used in ReQL for filtering and boosting according to your business rules.

post

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

Node.jsPythonRubyJavaPHPC#GoREST
Copy
Initialization
client.send(new requests.SetItemValues(itemId, values, {
  // optional parameters:
  cascadeCreate: true,  // boolean
}));
databaseId
String
Located in: path
Required: Yes

ID of your database.

itemId
String
Located in: path
Required: Yes

ID of the item which will be modified.

Object
Located in: body
Required: Yes

The values for the individual properties.

Example of the body:

  {
    "product_description": "4K TV with 3D feature",
    "categories":   ["Electronics", "Televisions"],
    "price_usd": 342,
    "in_stock_from": "2016-11-16T08:00Z",
    "image": "http://myexamplesite.com/products/4ktelevision3d/image.jpg",
    "other_images": ["http://myexamplesite.com/products/4ktelevision3d/image2.jpg",
                     "http://myexamplesite.com/products/4ktelevision3d/image3.jpg"]
  }

Set item values can also cascade create the item 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:

      {
    "product_description": "4K TV with 3D feature",
    "!cascadeCreate": true
  }

    Note the exclamation mark (!) at the beginning of the parameter's name to distinguish it from item property names.

200

Successful operation.

400

Property name does not match ''^[a-zA-Z0-9_-:]+$'', value does not match the 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

Gets all the current property values of the given item.

Node.jsPythonRubyJavaPHPC#GoREST
Copy
Initialization
const result = await client.send(new requests.GetItemValues(itemId));
databaseId
String
Located in: path
Required: Yes

ID of your database.

itemId
String
Located in: path
Required: Yes

ID of the item whose properties are to be obtained.

200

Successful operation.

{
  "release-date": null,
  "tags": [
    "electronics",
    "laptops"
  ],
  "num-processors": 12,
  "description": "Very powerful laptop",
  "weight": 1.6
}
400

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

404

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

post

Updates (some) property values of all the items that pass the filter.

Example: Setting all the items that are older than a week as unavailable

  {
    "filter": "'releaseDate' < now() - 7*24*3600",
    "changes": {"available": false}
  }
Node.jsPythonRubyJavaPHPC#GoREST
Copy
Initialization
const result = await client.send(new requests.UpdateMoreItems(filter, changes));
Since version
3.3.0
databaseId
String
Located in: path
Required: Yes
Since version: 3.3.0

ID of your database.

filter
String
Located in: body
Required: Yes
Since version: 3.3.0

A ReQL expression, which returns true for the items that shall be updated.

changes
Object
Located in: body
Required: Yes
Since version: 3.3.0

A dictionary where the keys are properties that shall be updated.

200

Successful operation. Returns IDs of updated items and their count.

{
  "itemIds": [
    "item-42",
    "item-125",
    "item-11"
  ],
  "count": 3
}
400

Invalid filter, property name does not match ''^[a-zA-Z0-9_-:]+$'', value does not match the property type.

404

Property of the given name is not present in the database.

© Copyright 2026, Recombee s.r.o
docs.recombee.com