Skip to main content

Entities

Overview​

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

Models​

Entity​

class Entity(BaseModel):
    """
    Pydantic model describes Entity in BuiltAPI
    """
    id: str
    createdAt: datetime
    updatedAt: datetime
    workspaceId: str
    name: str
    type: EntityType
    dateSettings: Optional[List[DateSettings]] = list()
    geoSettings: Optional[List] = list() # Not implemented yet
    jsonSchema: Optional[Dict] = None # Not implemented yet

EntityList​

class ListModel(BaseModel):
    skip: int
    take: int
    count: int
    total: int
    items: List[Entity]

Methods​

list​

List entities with optional search and ordering.

Parameters​

  • skip (int, optional): Number of entities to skip. Default is 0.
  • take (int, optional): Number of entities to take. Default is 100.
  • search (Optional[Dict[str, Any]], optional): Search criteria.
  • orderBy (Optional[List[Dict[str, str]]], optional): Ordering criteria.

Returns​

  • EntitiesList: A list of entities.

Example​

from builtapi import BuiltAPI

client = BuiltAPI()
entities = client.entities.list(skip=0, take=50, 
                                search={'name': 'example'}, 
                                orderBy=[{'name': 'asc'}])\
print(entities)

Search parameters​

You can search entities by the following fields: ids, name, types.

With ids you can search by multiple entity IDs. example

from builtapi import BuiltAPI

client = BuiltAPI()
entities = client.entities.list(search={'ids': ["id1", "id2"]})
print(entities)

With types you can search by multiple entity types.

from builtapi import BuiltAPI, EntityType

client = BuiltAPI()
entities = client.entities.list(search={'types': [EntityType.REGULAR, EntityType.LOGS]})
print(entities)

Ordering parameters​

You can order entities by the following fields: name, createdAt, updatedAt. Each field define in dictionary with key as field name and value as order direction.

example

from builtapi import BuiltAPI

client = BuiltAPI()
entities = client.entities.list(orderBy=[{'name': 'asc'}, {'createdAt': 'desc'}])
print(entities)

oneById​

Retrieve a single entity by its ID.

Parameters​

  • entityId (str): The ID of the entity to retrieve.

Returns​

  • Entity: The entity with the specified ID.

Example​

from builtapi import BuiltAPI

client = BuiltAPI()
entity = client.entities.oneById(entityId='entity_id')
print(entity)

create​

Create a new entity.

Parameters​

  • name (str): The name of the entity.
  • type (EntityType): The type of the entity. Default is EntityType.REGULAR.
  • dateSettings (Optional[List[DateSettings | dict]]): Date settings for the entity.

Returns​

Entity: The newly created entity.

Example​

from builtapi import BuiltAPI, EntityType

new_entity = client.entities.create(
    name='New Entity',
    type=EntityType.REGULAR
)
print(new_entity)

Date Settings​

Date Settings is optional settings for date fields. If the entity data contains date fields, you must specify the source field, target field, source type and source format. BuiltAPI will automatically convert the date fields to BuiltAPI date format.

  • sourcePath: Path to the original date field.
  • targetKey: Path to the converted field in the entity record
  • type: Type of date field:
    • ISO: ISO8601 format. Example: 2023-01-01T00:00:00Z
    • Seconds: UNIX timestamp in seconds. Example: 1609459200
    • Milliseconds: UNIX timestamp in milliseconds. Example: 1609459200000
    • Custom: If the date format is not one of the above, you can specify a custom format. The format must be a valid JS time format string.

Example

datesettings = [
    {
        "type": "ISO",
        "sourcePath": "dob",
        "targetKey": "dob_iso"
    }
]

new_entity = client.entities.create(
    name='New Entity',
    type=EntityType.REGULAR,
    dateSettings=datesettings,
)

update​

Update an existing entity.

Parameters​

  • entityId (str): The ID of the entity to update.
  • name (Optional[str]): The new name of the entity.
  • dateSettings (Optional[List[DateSettings | dict]]): New date settings for the entity.

Returns​

Entity: The updated entity.

Example​

from builtapi import BuiltAPI

client = BuiltAPI()
updated_entity = client.entities.update(
    entityId='entity_id',
    name='Updated Entity'
)
print(updated_entity)

remove​

Remove an entity by its ID.

Parameters​

  • entityId (str): The ID of the entity to remove.

Returns​

  • entities_schemas.Entity: The removed entity.

Example​

removed_entity = client.entities.remove(entityId='entity_id')
print(removed_entity)