Skip to main content

Records

Overview

The Records module provides methods to interact with records in the BuiltAPI platform. This module allows you to list, retrieve, create, update, and remove records.

Methods​

list​

List records with optional search and ordering.

Parameters​

  • entityId (str): The ID of the entity.
  • filter (Optional[Dict[str, Any]]): Filter object.
  • take (int): Number of records to take. Default is 100.
  • skip (int): Number of records to skip. Default is 0.
  • sort (Optional[Dict[str, str]]): Sorting object.
  • projection (Optional[Dict[str, bool]]): Fields to include or exclude.

Returns​

  • RecordsList: A list of records.

Example​

from builtapi import BuiltAPI

client = BuiltAPI()
records = client.records.list(
    entityId='entity_id', 
    filter={'field1': 'value'}, 
    take=50, 
    skip=0, 
    sort={'field1': 'asc'}, 
    projection={'field1': True, 'field2': False}
)
print(records)

get_one​

Return one record.

Parameters​

  • entityId (str): The ID of the entity.
  • filter (Optional[Dict[str, Any]], optional): Filter object.
  • projection (Optional[Dict[str, bool]], optional): Fields to include or exclude.

Returns​

  • Record: The requested record.

Example​

from builtapi import BuiltAPI

client = BuiltAPI()
record = client.records.get_one(
    entityId='entity_id', 
    filter={'field1': 'value'}, 
    projection={'field1': True, 'field2': False}
)
print(record)

replace_one​

Replace an first existing record identified by filter.

Parameters​

  • entityId (str): The ID of the entity.
  • filter (Dict[str, Any]): Filter object to identify the record to replace.
  • data (Dict): The new data for the record.
  • upsert (Optional[bool]): Whether to insert the record if it does not exist. Default is False.

Returns​

  • Record: The replaced record.

Example​

from builtapi import BuiltAPI

client = BuiltAPI()
replaced_record = client.records.replace_one(
    entityId='entity_id', 
    filter={'field1': 'value'}, 
    data={'field1': 'new_value1', 'field2': 'new_value2'}, 
    upsert=True
)
print(replaced_record)

update_one​

Update first existing record identified by filter.

Parameters​

  • entityId (str): The ID of the entity.
  • filter (Dict[str, Any]): Filter object to identify the record to update.
  • data (Dict): The new data for the record.
  • upsert (Optional[bool], optional): Whether to insert the record if it does not exist. Default is False.

Returns​

  • Record: The updated record.

Example​

from builtapi import BuiltAPI

client = BuiltAPI()
updated_record = client.records.update_one(
    entityId='entity_id', 
    filter={'field1': 'value'}, 
    data={'field1': 'updated_value1', 'field2': 'updated_value2'}, 
    upsert=True
)
print(updated_record)

remove_one​

Remove a record.

Parameters​

  • entityId (str): The ID of the entity.
  • filter (Dict[str, Any]): Filter criteria to identify the record to remove.

Returns​

  • Record: The removed record.

Example​

from builtapi import BuiltAPI

client = BuiltAPI()
removed_record = client.records.remove_one(
    entityId='entity_id', 
    filter={'field1': 'value'}
)
print(removed_record)

update_many​

Update multiple records.

Parameters​

  • entityId (str): The ID of the entity.
  • filter (Dict[str, Any]): Filter criteria to identify the records to update.
  • data (Dict): The new data for the records.
  • upsert (Optional[bool]): Whether to insert the records if they do not exist. Default is False.

Returns​

  • UpdateManyResult: The result of the update operation.

Example​

from builtapi import BuiltAPI

client = BuiltAPI()
update_many_result = client.records.update_many(
    entityId='entity_id', 
    filter={'field1': 'value'}, 
    data={'field1': 'updated_value1', 'field2': 'updated_value2'}, 
    upsert=True
)
print(update_many_result)

remove_many​

Remove multiple records.

Parameters​

  • entityId (str): The ID of the entity.
  • filter (Dict[str, Any]): Filter criteria to identify the records to remove.

Returns​

  • RemoveManyResult: The result of the remove operation.

Example​

from builtapi import BuiltAPI

client = BuiltAPI()
remove_many_result = client.records.remove_many(
    entityId='entity_id', 
    filter={'field1': 'value'}
)
print(remove_many_result)

create_bulk​

Create multiple records in bulk.

Parameters​

  • entityId (str): The ID of the entity.
  • items (List[RecordCreateSchema]): A list of records to create.

Returns​

  • BulkResult: The result of the bulk create operation.

Example​

from builtapi import BuiltAPI

client = BuiltAPI()
bulk_create_result = client.records.create_bulk(
    entityId='entity_id', 
    items=[
        {
            "data":
            {
                "first_name": "Artem",
                "last_name": "Kolichenko",
                "email": "artem.kolichenko.mail.com",
                "dbo": datetime.datetime(1995, 10, 10)
            }
        },
        {
            "data": {
                "first_name": "Artem",
                "last_name": "Ivanov",
                "email": "ivan.ivanov.mail.com",
                "dbo": datetime.datetime(1985, 10, 10)
            }
        }
    ]
)
print(bulk_create_result)

replace_bulk​

Replace multiple records in bulk.

Parameters​

  • entityId (str): The ID of the entity.
  • items (List[RecordReplaceSchema]): A list of records to replace.

Returns​

  • BulkResult: The result of the bulk replace operation.

Example​

from builtapi import BuiltAPI

client = BuiltAPI()
bulk_replace_result = client.records.replace_bulk(
    entityId='entity_id', 
    items=[
        {
            "filter": {"data.first_name": "Artem"},
            "data": {
                "first_name": "Zigmund",
                "last_name": "Freid"
            },
            "upsert": True
        },
        {
            "filter": {"data.first_name": "Ivan"},
            "data": {
                "first_name": "Karl",
                "last_name": "Marks"
            }
        }
    ]
)
print(bulk_replace_result)

update_bulk​

Update multiple records in bulk.

Parameters​

  • entityId (str): The ID of the entity.
  • items (List[RecordUpdateSchema]): A list of records to update.

Returns​

  • BulkResult: The result of the bulk update operation.

Example​

from builtapi import BuiltAPI

client = BuiltAPI()
bulk_update_result = client.records.update_bulk(
    entityId='entity_id', 
    items=[
        {
            "filter": {"data.first_name": "Artem"},
            "data": {
                "first_name": "Zigmund",
                "last_name": "Freid"
            },
            "upsert": True
        },
        {
            "filter": {"data.first_name": "Ivan"},
            "data": {
                "first_name": "Karl",
                "last_name": "Marks"
            }
        }
    ]
)
print(bulk_update_result)

remove_bulk​

Remove multiple records in bulk.

Parameters​

  • entityId (str): The ID of the entity.
  • items (List[RecordRemoveSchema]): A list of records to remove.

Returns​

  • BulkResult: The result of the bulk remove operation.

Example​

from builtapi import BuiltAPI

client = BuiltAPI()
bulk_remove_result = client.records.remove_bulk(
    entityId='entity_id', 
    items=[
        {
            "filter": {"data.first_name": "Artem"}
        },
        {
            "filter": {"data.first_name": "Ivan"}
        }
    ]
)
print(bulk_remove_result)

Schemas​

Record​

{ "_id": str, "data": Dict[str, Any], "meta": { "createdAt": datetime, "updatedAt": datetime } "pipelines: Dict[str, RecordPipelineMeta] }

RecordsList​

{ skip: int take: int count: int total: int items: List[Record] }

RecordPipelineMeta​

{ "processedAt": datetime, "meta": Dict[str, Any] }

BulkResult​

{ errors: List[BulkResultError] insertedIds: Dict[str, str] insertedCount: int upsertedIds: Dict[str, str] upsertedCount: int matchedCount: int modifiedCount: int deletedCount: int }

BulkResultError​

{ code: int index: int errmsg: str op: Dict }

RecordCreateSchema​

{ "data": Dict[str, Any] }

RecordReplaceSchema​

{ filter: Dict[[str, Any] data: Dict[str, Any] upsert: Optional[Bool] = False }

RecordUpdateSchema​

{ filter: Dict[str, Any] data: Dict[str, Any] upsert: Optional[Bool] = False }

RecordRemoveSchema​

{ filter: Dict[str, Any] }