Skip to content

Manage dataitems

The CRUD methods are used to read, update, and delete dataitems. They can be called through the SDK or through the Project object. When managing dataitems from a project, omit the project parameter and pass every other parameter as a keyword argument. For dataitem creation functions, see the Create a dataitem guide.

Read

Use the read methods to retrieve dataitems from the backend or load them from a YAML descriptor.

get_dataitem

Get a dataitem entity from the backend.

Parameters:

Name Type Description Default
identifier str

Entity name or entity key (store://<project>/<entity_type>/<kind>/<(name>:)<uuid>).

required
project str

Project name. Required when identifier is an entity name.

None
entity_id str

Entity identifier. If omitted, the latest version is returned.

None

Returns:

Type Description
Dataitem

Retrieved dataitem entity.

Examples:

Retrieve the latest version by name and project, or by entity key:

import digitalhub as dh

dataitem = dh.get_dataitem("raw-events", "my-project")
dataitem = dh.get_dataitem("store://my-project/dataitem/dataitem/raw-events:123e4567-e89b-42d3-a456-426614174000")
get_dataitem_versions

Get all versions of a dataitem entity from the backend.

Parameters:

Name Type Description Default
identifier str

Entity name or entity key (store://<project>/<entity_type>/<kind>/<(name>:)<uuid>).

required
project str

Project name. Required when identifier is an entity name.

None

Returns:

Type Description
list[Dataitem]

All versions of the dataitem entity.

Examples:

Retrieve all versions by name and project, or by entity key:

import digitalhub as dh

dataitems = dh.get_dataitem_versions("raw-events", "my-project")
dataitems = dh.get_dataitem_versions(
    "store://my-project/dataitem/dataitem/raw-events:123e4567-e89b-42d3-a456-426614174000"
)
list_dataitems

List dataitem entities in a project.

Parameters:

Name Type Description Default
project str

Project name.

required
q str

Query string used to filter entities.

None
name str

Entity name used to filter results.

None
kind str

Entity kind used to filter results.

None
labels list[str]

Labels used to filter results.

None
user str

User who created the entity.

None
state str

Entity state used to filter results.

None
created str

Creation date filter.

None
updated str

Update date filter.

None
versions str

Version filter. Defaults to the latest version.

None

Returns:

Type Description
list[Dataitem]

Dataitem entities matching the filters.

Examples:

List dataitems in a project:

import digitalhub as dh

dataitems = dh.list_dataitems(project="my-project")
import_dataitem

Import a dataitem entity from a YAML file or entity key.

Parameters:

Name Type Description Default
file str

Path to a YAML file containing the entity descriptor. Provide either file or key.

None
key str

Entity key (store://<project>/<entity_type>/<kind>/<(name>:)<uuid>). Provide either file or key.

None
reset_id bool

Whether to generate a new entity identifier instead of preserving the identifier from the imported entity.

False
context str

Project name used for context resolution. If omitted, the project from the entity descriptor is used.

None

Returns:

Type Description
Dataitem

Imported dataitem entity.

Examples:

Import a dataitem from a YAML file or entity key:

import digitalhub as dh

dataitem = dh.import_dataitem(file="my-dataitem.yaml")
dataitem = dh.import_dataitem(
    key="store://my-project/dataitem/dataitem/raw-events:123e4567-e89b-42d3-a456-426614174000"
)
load_dataitem

Load a dataitem entity from a YAML file.

Parameters:

Name Type Description Default
file str

Path to a YAML file containing the entity descriptor.

required

Returns:

Type Description
Dataitem

Loaded dataitem entity. An existing entity is updated when it can be identified; otherwise, a new entity is created.

Examples:

Load a dataitem descriptor from a YAML file:

import digitalhub as dh

dataitem = dh.load_dataitem("my-dataitem.yaml")

Update

Update a dataitem after changing its mutable metadata.

update_dataitem

Update a dataitem entity in the backend.

Parameters:

Name Type Description Default
entity Dataitem

Entity to update. The entity specification is immutable.

required

Returns:

Type Description
Dataitem

Updated dataitem entity.

Examples:

Update a dataitem after changing its mutable metadata:

import digitalhub as dh

dataitem = dh.get_dataitem("raw-events", "my-project")
dataitem.set_description("Updated dataitem")
dataitem = dh.update_dataitem(dataitem)

Delete

Delete one dataitem version or all versions of a dataitem.

delete_dataitem

Delete one or more versions of a dataitem entity from the backend.

Parameters:

Name Type Description Default
identifier str

Entity name or entity key (store://<project>/<entity_type>/<kind>/<(name>:)<uuid>). Use an entity name when delete_all_versions is True.

required
project str

Project name. Required when identifier is an entity name.

None
entity_id str

Identifier of the version to delete. Required when delete_all_versions is False and identifier does not contain the version identifier.

None
delete_all_versions bool

Whether to delete all versions of the named entity. When False, only one version is deleted.

False
cascade bool

Whether to request cascade deletion from the backend.

True
**kwargs dict

Additional parameters to pass to the API call.

{}

Returns:

Type Description
dict

Response data from the backend.

Examples:

Delete a version by key, or delete all versions by name and project:

import digitalhub as dh

dh.delete_dataitem("store://my-project/dataitem/dataitem/raw-events:123e4567-e89b-42d3-a456-426614174000")
dh.delete_dataitem("raw-events", "my-project", delete_all_versions=True)