Properties

In Collect, you can store meaningful data using Properties. Properties are fundamental data units, representing individual pieces of information as key-value pairs.

TypeScript Definition

type CollectPropertyType = "number" | "string" | "boolean" | "datetime" | "null";

export type CollectProperty = {
    id: string;
    metadata?: string;
    name: string;
    type: CollectPropertyType;
    // If retrieving a property within a record
    value: CollectPropertyValue;
    // If retrieving property values via Properties API
    max?: number;
    min?: number;
    values: CollectPropertyValue[];
};

Each property type has specific values that correspond to its type. The datetime type can have a value of either a string or an object:

export type CollectDatetimeObject = {
    $year: number;
    $month?: number;
    $day?: number;
    $hour?: number;
    $minute?: number;
    $second?: number;
    $millisecond?: number;
    $microsecond?: number;
    $nanosecond?: number;
};

How It Works

Imagine a property as a column in a database that represents a specific attribute or piece of information. While the overall data structure may include complex graph structures or records, at the core of each property is a simple key-value pair. You can think of a property as an element in a "dictionary," "map," "hash table," or "associative array," depending on your programming language or context.

Properties are combined into records, which can be viewed as rows in a database containing multiple properties. This allows you to structure data in a flexible and intuitive way, where each property adds specific information to a record.

---

Create Property

Properties cannot be created directly, as they serve as descriptors of records. The creation of new properties and their automatic deletion occur directly within the Records API.

---

Get Property

Endpoint

Retrieve the values of a single property across all records:

GET /api/v1/properties/:propertyId/values

info

Note: Replace :propertyId with the actual ID of the property you want to retrieve.

To retrieve a property in Collect, you can use the .values method or make a GET request to the REST API endpoint.

Request

// You can achieve the same result with the `.findById` method.
const property = await Collect.properties.values(
    "0192397b-8579-7ce2-a899-01c59bad63f8"
    );

Response

{
    "metadata": "",
    "values": [
        "Alice Johnson",
        "Best Shoe Store",
        "John Doe"
    ],
    "name": "name",
    "id": "0192397b-8579-7ce2-a899-01c59bad63f8",
    "type": "string",
    "projectId": "0191d2a4-6d9d-7967-82b5-6155899aeb91"
}

Get Record Related Properties

Endpoint

You can easily fetch properties related to a specific record:

GET /api/v1/records/:entityId/properties

info

Note: Replace :entityId with the actual ID of the record whose properties you want to retrieve.

To retrieve the properties related to a record in Collect, use the .properties method or make a GET request to the REST API endpoint.

Request

// Retrieve properties related to the specified record.
const properties = await Collect.records.properties(
    "019239e7-d3b5-7840-9338-d536b98b4b2d"
);

Response

[
    {
        "metadata": "",
        "name": "email",
        "id": "019239e7-d3b5-7840-9338-d53591c0e285",
        "type": "string",
        "projectId": "0191d2a4-6d9d-7967-82b5-6155899aeb91"
    },
    {
        "metadata": "",
        "name": "username",
        "id": "019239e7-d3b5-7840-9338-d534d70b9ea6",
        "type": "string",
        "projectId": "0191d2a4-6d9d-7967-82b5-6155899aeb91"
    },
    {
        "metadata": "",
        "name": "name",
        "id": "0192397b-8579-7ce2-a899-01c59bad63f8",
        "type": "string",
        "projectId": "0191d2a4-6d9d-7967-82b5-6155899aeb91"
    }
]

---

Search

Endpoint

Search from root:

POST /api/v1/properties

To build more complex and unique structures (for example, dynamic filters), you may require a more flexible way to obtain properties. You can retrieve all relevant properties that satisfy the current search parameters using the .find method.

Request

await Collect.properties.find({
    labels: ['SHOP'],
    where: {
        name: { $contains: "Best Shoe" },
        PRODUCT: {
            $relation: { direction: 'out', type: 'sells' },
            title: { $contains: "Dr. Martens" },
            SELLER: {
                $relation: { direction: 'in', type: 'sold' },
                name: "John Doe",
            },
            CLIENT: {
                $relation: { direction: 'in', type: 'purchased' },
            },
        },
    },
});

Response

[
    {
        "metadata": "",
        "name": "name",
        "id": "0192397b-8579-7ce2-a899-01c59bad63f8",
        "type": "string",
        "projectId": "0191d2a4-6d9d-7967-82b5-6155899aeb91"
    },
    {
        "metadata": "",
        "name": "location",
        "id": "019239e7-01dc-70af-907a-7059c3b9e33a",
        "type": "string",
        "projectId": "0191d2a4-6d9d-7967-82b5-6155899aeb91"
    }
]
// All available properties of those stores where John sold Dr. Martens

---

Update Property Values for Selected Records

Endpoint

PATCH /api/v1/properties/:propertyId/values

info

Note: Replace :propertyId with the actual ID of the property whose values you want to update.

Sometimes you may need to bulk edit values with new ones. You can send single or multiple values along with the IDs of target records. New values will replace the old ones.

danger

Warning: If no newValue is provided, the property will be deleted. Also, newValue must be of the same type as the property.

If no entityIds are provided, all values in all records will be overwritten with the new values.

Request

PATCH /api/v1/properties/019239e7-d33a-7b31-933d-680df398a4d1/values

{
    "entityIds": ["019239e7-d3b5-7840-9338-d536b98b4b2d", "019239e7-d2b8-7131-89d0-914ea5ff8ef9"],
    "newValue": ["Dr Martens 1460", "Dr Martens 1460 Jadon Black Chunky Heel"]
}

Response

{
    "success": true
}

---

Update Property Attributes

info

This part of the documentation is actively in development.

If you encounter any issues while using it, we kindly request that you notify us through any available channels or contact us directly at hello@collect.so or @CollectAPI on X.

---

Delete Property

Endpoint

DELETE /api/v1/properties/:propertyId

info

Note: Replace :propertyId with the actual ID of the property you want to delete.

To completely remove a property and all its values, simply call the .delete method with the property ID.

Request

DELETE /api/v1/properties/019239e7-d33a-7b31-933d-680df398a4d1

Response

{
    "success": true
}

---

Endpoints Overview

The Properties API provides several endpoints to work with. Here's an overview of all available endpoints in this section:

Method	Endpoint	Description
GET	/api/v1/properties/:propertyId/values	Get a single property with available values
GET	/api/v1/records/:entityId/properties	Get available properties for a record
POST	/api/v1/properties	Get a list of properties by search parameters
PATCH	/api/v1/properties/:propertyId/values	Edit property values for selected records
DELETE	/api/v1/properties/:propertyId	Delete a property