Base Entity¶

The BaseEntity class is the foundation that all Everysk entities build upon. Every entity — Custom Index, Datastore, File, Portfolio, Private Security, Report, Secrets, Worker Execution, Workflow, Workflow Execution, and Workspace — inherits from it, gaining a shared set of methods for creation, retrieval, modification, deletion, cloning, and querying.

Lets take a look a them below.

Create¶

Use create() to persist a new entity. Pass a dictionary with the entity's attributes and get back the created instance:

from everysk.sdk.entities import Portfolio

portfolio = Portfolio.create({
    'name': 'My Portfolio',
    'workspace': 'main',
    'date': '20210622',
    'securities': [
        {'id': 'id1', 'symbol': 'AAPL', 'quantity': 1000.0},
        {'id': 'id2', 'symbol': 'MSFT', 'quantity': 500.0},
    ],
})

portfolio.id
# 'port_V7xU8dwCMnJIuyUPHJPx2ynuz'

Retrieve¶

Use retrieve() to fetch an existing entity by its ID. Returns the entity instance, or None if not found:

portfolio = Portfolio.retrieve('port_V7xU8dwCMnJIuyUPHJPx2ynuz')

portfolio.name
# 'My Portfolio'

portfolio.date
# '20210622'

Modify¶

Use modify() to update an existing entity. Pass the entity ID and a dictionary of fields to overwrite. Returns the updated instance, or None if not found:

portfolio = Portfolio.modify(
    'port_V7xU8dwCMnJIuyUPHJPx2ynuz',
    {
        'name': 'My Updated Portfolio',
        'securities': [
            {'id': 'id3', 'symbol': 'GOOGL', 'quantity': 300.0},
        ],
    },
)

portfolio.name
# 'My Updated Portfolio'

Remove¶

Use remove() to permanently delete an entity by its ID. Returns the deleted instance, or None if not found:

deleted = Portfolio.remove('port_V7xU8dwCMnJIuyUPHJPx2ynuz')

deleted.id
# 'port_V7xU8dwCMnJIuyUPHJPx2ynuz'

Delete¶

Use delete() to permanently delete an entity instance directly, without needing its ID separately:

portfolio = Portfolio.retrieve('port_V7xU8dwCMnJIuyUPHJPx2ynuz')
portfolio.delete()

Remove Many¶

Use remove_many() to permanently delete multiple entities in bulk by passing a list of IDs:

Portfolio.remove_many([
    'port_abc123',
    'port_def456',
    'port_ghi789',
])

Script API¶

The script interface provides lower-level methods used to fetch and persist entities within worker contexts. Each entity class exposes a script attribute with the following methods:

fetch¶

Fetches a single entity by query, variant, and workspace. Returns the entity instance or None if not found:

datastore = Datastore.script.fetch('dats_abc123', 'id', 'main')

# fetch by tag (latest)
datastore = Datastore.script.fetch('my-tag', 'tagLatest', 'main')

# fetch by link_uid (latest)
portfolio = Portfolio.script.fetch('my-link', 'linkLatest', 'main')

fetch_list¶

Fetches a list of entities by query, variant, and workspace:

datastores = Datastore.script.fetch_list(['dats_abc123', 'dats_def456'], 'id', 'main')

fetch_multi¶

Fetches multiple entities at once using separate lists of queries, variants, and workspaces. Useful when each entity may come from a different workspace or use a different lookup variant:

datastores = Datastore.script.fetch_multi(
    ['dats_abc123', 'dats_def456'],
    ['id', 'id'],
    ['workspace_a', 'workspace_b'],
)

storage¶

Persists an entity according to the provided storage_settings. This is the standard way to save an entity inside a worker after building or modifying it:

storage_settings = BaseMapping(mode='create')  # or 'update', 'transient'
datastore = Datastore.script.storage(datastore, storage_settings)

Now that we've seen the shared CRUD interface, let's take a closer look at each entity individually — their specific attributes, behaviors, and usage patterns.