Datalens SDK¶

Examples use a client built as datalens = DataLensClient(oauth_token="…", organization_id="…").

DataLensClient ¶

DataLensClient(*, oauth_token: str | None = None, auth: Auth | None = None, organization_id: str | None = None, cloud_organization_id: str | None = None, http: HTTPConfig | None = None, transport: BaseTransport | None = None, before_send: BeforeSend | None = None, guard: Guard | None = None)

Bases: DomainClient

Holds the per-resource DataLens clients, all sharing one httpx2 core session.

Examples:

>>> datalens.tenant.details_get().tenant_id
'org_bpf00000000000000000'

probe ¶

probe() -> None

One cheap authenticated read: the details of the DataLens instance.

tenant¶

TenantClient ¶

TenantClient(*, session: SyncSession)

Bases: Resource

The DataLens instance of the organization.

details_get ¶

details_get() -> TenantDetails

getTenantDetails → the instance the credentials reach (a safe auth probe).

Returns:

Type	Description
`TenantDetails`	The tenant: its id, the organization it belongs to and its public settings.

Examples:

>>> datalens.tenant.details_get().tenant_id
'org_bpf00000000000000000'

collections¶

CollectionsClient ¶

CollectionsClient(*, session: SyncSession)

Bases: Resource

Collections: the folders of DataLens that hold workbooks and other collections.

get ¶

get(collection_id: str, *, include_permissions_info: bool | None = None) -> CollectionDetails

getCollection → one collection.

Parameters:

Name	Type	Description	Default
`collection_id`	`str`	The collection's id.	required
`include_permissions_info`	`bool \| None`	Also say what the caller may do with it.	`None`

Returns:

Type	Description
`CollectionDetails`	The collection.

Examples:

>>> datalens.collections.get("col00000000001").title
'Sales'

list_by_ids ¶

list_by_ids(collection_ids: Sequence[str]) -> ItemList[Collection]

getCollectionsByIds → the collections with these ids.

Parameters:

Name	Type	Description	Default
`collection_ids`	`Sequence[str]`	The ids of the collections.	required

Returns:

Type	Description
`ItemList[Collection]`	The collections found; an id the caller cannot see is left out.

Examples:

>>> ids = ["col00000000001", "col00000000002"]
>>> [found.title for found in datalens.collections.list_by_ids(ids).root]
['Sales', 'Finance']

content_list ¶

content_list(collection_id: str | None = None, *, limit: int | None = None, next: str | None = None, filter_string: str | None = None, order_field: OrderField | None = None, order_direction: SortDirection | None = None, only_my: bool | None = None, mode: ContentMode | None = None, include_permissions_info: bool | None = None) -> Listing[ContentItem]

getCollectionContent → what a collection holds, draining nextPageToken.

Capped at limit (None = every item).

Parameters:

Name	Type	Description	Default
`collection_id`	`str \| None`	The collection's id; the root when left out.	`None`
`limit`	`int \| None`	The most items to return; `None` returns every item.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`
`filter_string`	`str \| None`	Keep the items whose title has this text.	`None`
`order_field`	`OrderField \| None`	What to sort by: `title`, `createdAt` or `updatedAt`.	`None`
`order_direction`	`SortDirection \| None`	The sort direction: `asc` or `desc`.	`None`
`only_my`	`bool \| None`	Keep only what the caller created.	`None`
`mode`	`ContentMode \| None`	Which kinds to list: `all`, `onlyCollections`, `onlyWorkbooks` or `onlyEntries`.	`None`
`include_permissions_info`	`bool \| None`	Also say what the caller may do with each item.	`None`

Returns:

Type	Description
`Listing[ContentItem]`	The collections, workbooks and entries of the collection.

Examples:

>>> items = (
...     datalens.collections.content_list("col00000000001", limit=45).collect().items
... )
>>> [item.title for item in items]
['Reports', 'Q1']

breadcrumbs_list ¶

breadcrumbs_list(collection_id: str, *, include_permissions_info: bool | None = None) -> ItemList[CollectionBreadcrumb]

getCollectionBreadcrumbs → the collections from the root down to this one.

Parameters:

Name	Type	Description	Default
`collection_id`	`str`	The collection's id.	required
`include_permissions_info`	`bool \| None`	Also say what the caller may do with each one.	`None`

Returns:

Type	Description
`ItemList[CollectionBreadcrumb]`	The path of collections, the root's child first.

Examples:

>>> path = datalens.collections.breadcrumbs_list("col00000000002").root
>>> [crumb.title for crumb in path]
['Sales', 'Finance']

permissions_get_root ¶

permissions_get_root() -> RootPermissions

getRootCollectionPermissions → what the caller may create in the root.

Returns:

Type	Description
`RootPermissions`	Whether the caller may create a collection and a workbook in the root.

Examples:

>>> datalens.collections.permissions_get_root().create_workbook_in_root
True

access_bindings_list ¶

access_bindings_list(collection_id: str, *, limit: int | None = None, next: str | None = None, get_inherited_bindings: bool | None = None) -> Listing[SubjectWithBindings]

listCollectionAccessBindings → who has which role, draining nextPageToken.

Capped at limit (None = every subject).

Parameters:

Name	Type	Description	Default
`collection_id`	`str`	The collection's id.	required
`limit`	`int \| None`	The most subjects to return; `None` returns every subject.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`
`get_inherited_bindings`	`bool \| None`	Also list the roles inherited from the collections above.	`None`

Returns:

Type	Description
`Listing[SubjectWithBindings]`	The subjects with their roles.

Examples:

>>> subjects = (
...     datalens.collections.access_bindings_list("col00000000001").collect().items
... )
>>> subjects[0].access_bindings[0].role_id
'datalens.collections.editor'

create ¶

create(*, title: str, parent_id: str | None = None, description: str | None = None) -> CollectionCreated

createCollection — create a collection.

Parameters:

Name	Type	Description	Default
`title`	`str`	The collection's title.	required
`parent_id`	`str \| None`	The collection to create it in; the root when left out.	`None`
`description`	`str \| None`	The collection's description.	`None`

Returns:

Type	Description
`CollectionCreated`	The created collection, with its `collection_id`.

Examples:

>>> datalens.collections.create(title="Sales").collection_id
'col00000000001'

update ¶

update(collection_id: str, *, title: str | None = None, description: str | None = None) -> Collection

updateCollection — change a collection's title or description.

Parameters:

Name	Type	Description	Default
`collection_id`	`str`	The collection's id.	required
`title`	`str \| None`	The new title.	`None`
`description`	`str \| None`	The new description.	`None`

Returns:

Type	Description
`Collection`	The collection as it is now.

Examples:

>>> datalens.collections.update("col00000000001", title="Sales 2026").title
'Sales 2026'

move ¶

move(collection_id: str, *, parent_id: str | None = None, title: str | None = None) -> Collection

moveCollection — move a collection into another one, or into the root.

Parameters:

Name	Type	Description	Default
`collection_id`	`str`	The collection's id.	required
`parent_id`	`str \| None`	The collection to move it into; the root when left out.	`None`
`title`	`str \| None`	A new title to give it on the way.	`None`

Returns:

Type	Description
`Collection`	The collection as it is now.

Examples:

>>> moved = datalens.collections.move("col00000000002", parent_id="col00000000001")
>>> moved.parent_id
'col00000000001'

move_bulk ¶

move_bulk(collection_ids: Sequence[str], *, parent_id: str | None = None) -> CollectionsMoved

moveCollections — move several collections into another one, or into the root.

All or none: if one collection already lies in the destination, the API answers 409 "The collection already exists" and moves none of them.

Parameters:

Name	Type	Description	Default
`collection_ids`	`Sequence[str]`	The ids of the collections.	required
`parent_id`	`str \| None`	The collection to move them into; the root when left out.	`None`

Returns:

Type	Description
`CollectionsMoved`	The moved collections.

Examples:

>>> ids = ["col00000000002", "col00000000003"]
>>> moved = datalens.collections.move_bulk(ids, parent_id="col00000000001")
>>> len(moved.collections)
2

delete ¶

delete(collection_id: str) -> CollectionsDeleted

deleteCollection — delete a collection with everything it holds.

Parameters:

Name	Type	Description	Default
`collection_id`	`str`	The collection's id.	required

Returns:

Type	Description
`CollectionsDeleted`	The deleted collections: the one named and those nested in it.

Examples:

>>> deleted = datalens.collections.delete("col00000000001")
>>> [found.title for found in deleted.collections]
['Sales', 'Finance']

delete_bulk ¶

delete_bulk(collection_ids: Sequence[str]) -> CollectionsDeleted

deleteCollections — delete several collections with everything they hold.

Parameters:

Name	Type	Description	Default
`collection_ids`	`Sequence[str]`	The ids of the collections.	required

Returns:

Type	Description
`CollectionsDeleted`	The deleted collections: those named and those nested in them.

Examples:

>>> ids = ["col00000000001", "col00000000002"]
>>> len(datalens.collections.delete_bulk(ids).collections)
2

access_bindings_update ¶

access_bindings_update(collection_id: str, *, deltas: Sequence[AccessBindingDelta]) -> Operation

updateCollectionAccessBindings — give or take away roles on a collection.

Each delta adds (ADD) or removes (REMOVE) one role of one subject; the roles not named stay as they are.

Parameters:

Name	Type	Description	Default
`collection_id`	`str`	The collection's id.	required
`deltas`	`Sequence[AccessBindingDelta]`	The roles to add and to remove.	required

Returns:

Type	Description
`Operation`	The operation that applies the change.

Examples:

>>> from ycli.yandex.datalens.models import AccessBindingDelta
>>> delta = AccessBindingDelta.model_validate(
...     {
...         "action": "ADD",
...         "accessBinding": {
...             "roleId": "datalens.collections.viewer",
...             "subject": {"id": "user-2", "type": "userAccount"},
...         },
...     }
... )
>>> datalens.collections.access_bindings_update("col00000000001", deltas=[delta]).done
True

workbooks¶

WorkbooksClient ¶

WorkbooksClient(*, session: SyncSession)

Bases: Resource

Workbooks: where connections, datasets, charts and dashboards live.

get ¶

get(workbook_id: str, *, include_permissions_info: bool | None = None) -> WorkbookDetails

getWorkbook → one workbook.

Parameters:

Name	Type	Description	Default
`workbook_id`	`str`	The workbook's id.	required
`include_permissions_info`	`bool \| None`	Also say what the caller may do with it.	`None`

Returns:

Type	Description
`WorkbookDetails`	The workbook.

Examples:

>>> datalens.workbooks.get("wb000000000001").title
'Q1'

list ¶

list(*, limit: int | None = None, next: str | None = None, collection_id: str | None = None, filter_string: str | None = None, order_field: OrderField | None = None, order_direction: SortDirection | None = None, only_my: bool | None = None, include_permissions_info: bool | None = None) -> Listing[WorkbookListed]

getWorkbooksList → the workbooks of a collection, draining nextPageToken.

Capped at limit (None = every workbook).

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	The most workbooks to return; `None` returns every workbook.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`
`collection_id`	`str \| None`	The collection to list; the root when left out.	`None`
`filter_string`	`str \| None`	Keep the workbooks whose title has this text.	`None`
`order_field`	`OrderField \| None`	What to sort by: `title`, `createdAt` or `updatedAt`.	`None`
`order_direction`	`SortDirection \| None`	The sort direction: `asc` or `desc`.	`None`
`only_my`	`bool \| None`	Keep only what the caller created.	`None`
`include_permissions_info`	`bool \| None`	Also say what the caller may do with each one.	`None`

Returns:

Type	Description
`Listing[WorkbookListed]`	The workbooks.

Examples:

>>> found = datalens.workbooks.list(collection_id="col00000000001", limit=45)
>>> [workbook.title for workbook in found]
['Q1', 'Q2']

list_by_ids ¶

list_by_ids(workbook_ids: Sequence[str]) -> ItemList[Workbook]

getWorkbooksByIds → the workbooks with these ids.

Parameters:

Name	Type	Description	Default
`workbook_ids`	`Sequence[str]`	The ids of the workbooks.	required

Returns:

Type	Description
`ItemList[Workbook]`	The workbooks found; an id the caller cannot see is left out.

Examples:

>>> ids = ["wb000000000001", "wb000000000002"]
>>> [found.title for found in datalens.workbooks.list_by_ids(ids).root]
['Q1', 'Q2']

access_bindings_list ¶

access_bindings_list(workbook_id: str, *, limit: int | None = None, next: str | None = None, get_inherited_bindings: bool | None = None) -> Listing[SubjectWithBindings]

listWorkbookAccessBindings → who has which role, draining nextPageToken.

Capped at limit (None = every subject).

Parameters:

Name	Type	Description	Default
`workbook_id`	`str`	The workbook's id.	required
`limit`	`int \| None`	The most subjects to return; `None` returns every subject.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`
`get_inherited_bindings`	`bool \| None`	Also list the roles inherited from the collections above.	`None`

Returns:

Type	Description
`Listing[SubjectWithBindings]`	The subjects with their roles.

Examples:

>>> subjects = datalens.workbooks.access_bindings_list("wb000000000001").collect().items
>>> subjects[0].access_bindings[0].role_id
'datalens.workbooks.editor'

entries_list ¶

entries_list(workbook_id: str, *, limit: int | None = None, next: str | None = None, include_permissions_info: bool | None = None, only_my: bool | None = None, created_by: str | None = None, scope: EntryScope | Sequence[EntryScope] | None = None, order_by: EntriesOrder | None = None, filters: EntriesFilters | None = None) -> Listing[WorkbookEntry]

getWorkbookEntries → what a workbook holds, draining nextPageToken.

Capped at limit (None = every entry).

Parameters:

Name	Type	Description	Default
`workbook_id`	`str`	The workbook's id.	required
`limit`	`int \| None`	The most entries to return; `None` returns every entry.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`
`include_permissions_info`	`bool \| None`	Also say what the caller may do with each entry.	`None`
`only_my`	`bool \| None`	Keep only what the caller created.	`None`
`created_by`	`str \| None`	Keep only what this user created.	`None`
`scope`	`EntryScope \| Sequence[EntryScope] \| None`	Keep only these kinds: one (`dash`) or several.	`None`
`order_by`	`EntriesOrder \| None`	What to sort by and in which direction.	`None`
`filters`	`EntriesFilters \| None`	Keep the entries whose name has a text.	`None`

Returns:

Type	Description
`Listing[WorkbookEntry]`	The connections, datasets, charts and dashboards of the workbook.

Examples:

>>> entries = (
...     datalens.workbooks.entries_list("wb000000000001", limit=45).collect().items
... )
>>> [(entry.scope.root, entry.key) for entry in entries]
[('dataset', 'Sales/orders'), ('dash', 'Sales/overview')]

create ¶

create(*, title: str, collection_id: str | None = None, description: str | None = None) -> WorkbookCreated

createWorkbook — create a workbook.

Parameters:

Name	Type	Description	Default
`title`	`str`	The workbook's title.	required
`collection_id`	`str \| None`	The collection to create it in; the root when left out.	`None`
`description`	`str \| None`	The workbook's description.	`None`

Returns:

Type	Description
`WorkbookCreated`	The created workbook, with its `workbook_id`.

Examples:

>>> datalens.workbooks.create(title="Q1", collection_id="col00000000001").workbook_id
'wb000000000001'

update ¶

update(workbook_id: str, *, title: str | None = None, description: str | None = None) -> Workbook

updateWorkbook — change a workbook's title or description.

Parameters:

Name	Type	Description	Default
`workbook_id`	`str`	The workbook's id.	required
`title`	`str \| None`	The new title.	`None`
`description`	`str \| None`	The new description.	`None`

Returns:

Type	Description
`Workbook`	The workbook as it is now.

Examples:

>>> datalens.workbooks.update("wb000000000001", title="Q1 2026").title
'Q1 2026'

move ¶

move(workbook_id: str, *, collection_id: str | None = None, title: str | None = None) -> Workbook

moveWorkbook — move a workbook into a collection, or into the root.

Parameters:

Name	Type	Description	Default
`workbook_id`	`str`	The workbook's id.	required
`collection_id`	`str \| None`	The collection to move it into; the root when left out.	`None`
`title`	`str \| None`	A new title to give it on the way.	`None`

Returns:

Type	Description
`Workbook`	The workbook as it is now.

Examples:

>>> moved = datalens.workbooks.move("wb000000000001", collection_id="col00000000002")
>>> moved.collection_id
'col00000000002'

move_bulk ¶

move_bulk(workbook_ids: Sequence[str], *, collection_id: str | None = None) -> WorkbooksMoved

moveWorkbooks — move several workbooks into a collection, or into the root.

All or none: if one workbook already lies in the destination, the API answers 409 "The workbook already exists" and moves none of them.

Parameters:

Name	Type	Description	Default
`workbook_ids`	`Sequence[str]`	The ids of the workbooks.	required
`collection_id`	`str \| None`	The collection to move them into; the root when left out.	`None`

Returns:

Type	Description
`WorkbooksMoved`	The moved workbooks.

Examples:

>>> ids = ["wb000000000001", "wb000000000002"]
>>> moved = datalens.workbooks.move_bulk(ids, collection_id="col00000000002")
>>> len(moved.workbooks)
2

delete ¶

delete(workbook_id: str) -> Workbook

deleteWorkbook — delete a workbook with everything it holds.

Deleting a workbook that is already deleted answers 500, not 404 (measured): a server error after a delete may mean the workbook is gone.

Parameters:

Name	Type	Description	Default
`workbook_id`	`str`	The workbook's id.	required

Returns:

Type	Description
`Workbook`	The deleted workbook.

Examples:

>>> datalens.workbooks.delete("wb000000000001").title
'Q1'

delete_bulk ¶

delete_bulk(workbook_ids: Sequence[str]) -> WorkbooksDeleted

deleteWorkbooks — delete several workbooks with everything they hold.

Parameters:

Name	Type	Description	Default
`workbook_ids`	`Sequence[str]`	The ids of the workbooks.	required

Returns:

Type	Description
`WorkbooksDeleted`	The deleted workbooks.

Examples:

>>> ids = ["wb000000000001", "wb000000000002"]
>>> len(datalens.workbooks.delete_bulk(ids).workbooks)
2

access_bindings_update ¶

access_bindings_update(workbook_id: str, *, deltas: Sequence[AccessBindingDelta]) -> Operation

updateWorkbookAccessBindings — give or take away roles on a workbook.

Each delta adds (ADD) or removes (REMOVE) one role of one subject; the roles not named stay as they are.

Parameters:

Name	Type	Description	Default
`workbook_id`	`str`	The workbook's id.	required
`deltas`	`Sequence[AccessBindingDelta]`	The roles to add and to remove.	required

Returns:

Type	Description
`Operation`	The operation that applies the change.

Examples:

>>> from ycli.yandex.datalens.models import AccessBindingDelta
>>> delta = AccessBindingDelta.model_validate(
...     {
...         "action": "ADD",
...         "accessBinding": {
...             "roleId": "datalens.workbooks.viewer",
...             "subject": {"id": "user-2", "type": "userAccount"},
...         },
...     }
... )
>>> datalens.workbooks.access_bindings_update("wb000000000001", deltas=[delta]).done
True

entrylocks¶

EntryLocksClient ¶

EntryLocksClient(*, session: SyncSession)

Bases: Resource

Locks on entries: the hold an editor takes on a dataset, a chart or a dashboard.

create ¶

create(entry_id: str, *, data: LockTerms) -> LockCreated

createEntryLock — lock an entry for editing.

The reply is the token alone: keep it, releasing and extending the lock take it. An entry that is already locked answers 423 ERR.US.ENTRY_IS_LOCKED with who holds the lock and until when, unless force is given.

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The entry's id.	required
`data`	`LockTerms`	How long to hold the lock, in milliseconds, and whether to replace a lock that is already there.	required

Returns:

Type	Description
`LockCreated`	The token of the lock: extending and releasing it take the token.

Examples:

>>> from ycli.yandex.datalens.entrylocks.models import LockTerms
>>> created = datalens.entrylocks.create(
...     "ent00000000001", data=LockTerms(duration=300000)
... )
>>> created.lock_token
'lock-token-1'

extend ¶

extend(entry_id: str, *, data: LockExtension) -> Lock

extendEntryLock — hold a lock longer.

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The entry's id.	required
`data`	`LockExtension`	The token of the lock and the new duration, in milliseconds.	required

Returns:

Type	Description
`Lock`	The lock as it is now, with when it expires.

Examples:

>>> from ycli.yandex.datalens.entrylocks.models import LockExtension
>>> terms = LockExtension(lock_token="lock-token-1", duration=600000)
>>> datalens.entrylocks.extend("ent00000000001", data=terms).expiry_date
'2026-10-06T12:10:00.000Z'

delete ¶

delete(entry_id: str, *, params: LockRelease) -> Lock

deleteEntryLock — release a lock.

An entry that is not locked answers 404 NOT_EXIST_LOCKED_ENTRY.

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The entry's id.	required
`params`	`LockRelease`	The token of the lock, or `force` to release a lock held by another.	required

Returns:

Type	Description
`Lock`	The lock that was released.

Examples:

>>> from ycli.yandex.datalens.entrylocks.models import LockRelease
>>> released = datalens.entrylocks.delete(
...     "ent00000000001", params=LockRelease(lock_token="lock-token-1")
... )
>>> released.entry_id
'ent00000000001'

members¶

MembersClient ¶

MembersClient(*, session: SyncSession)

Bases: Resource

Members: the users, groups and service accounts a role can be given to.

list ¶

list(*, limit: int | None = None, next: str | None = None, language: MemberLanguage | None = None, search: str | None = None, tab_id: MemberKind | None = None, filter: str | None = None) -> Listing[Member]

batchListMembers → the members of the organization, draining nextPageToken.

Capped at limit (None = every member). The sub of a member is the subject id a role is given to (access_bindings_update).

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	The most members to return; `None` returns every member.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`
`language`	`MemberLanguage \| None`	The language of the names: `en` or `ru`.	`None`
`search`	`str \| None`	Keep the members whose name or address has this text.	`None`
`tab_id`	`MemberKind \| None`	Keep one kind of subject, e.g. `USER_ACCOUNT` or `GROUP`.	`None`
`filter`	`str \| None`	A filter expression of the API.	`None`

Returns:

Type	Description
`Listing[Member]`	The members found.

Examples:

>>> found = datalens.members.list(search="ann", limit=45).collect().items
>>> [(member.sub, member.email) for member in found]
[('user-1', 'ann@example.com'), ('user-2', 'anna@example.com')]

entries¶

EntriesClient ¶

EntriesClient(*, session: SyncSession)

Bases: Resource

Entries: the connections, datasets, charts and dashboards of the whole organization.

list ¶

list(*, limit: int | None = None, next: str | None = None, ids: Sequence[str] | None = None, scope: EntryScope | None = None, scopes: Sequence[EntryScope] | None = None, type: str | Sequence[str] | None = None, created_by: Sequence[str] | None = None, order_by: ListOrder | None = None, exclude_locked: bool | None = None, include_links: bool | None = None, filters: ListFilters | None = None, include_permissions_info: bool | None = None, ignore_workbook_entries: bool | None = None, ignore_shared_entries: bool | None = None, include_data: bool | None = None) -> Listing[Entry]

getEntries → entries across the organization, draining nextPageToken.

The API requires one of scope, scopes and ids. Capped at limit (None = every entry found).

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	The most entries to return; `None` returns every entry.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`
`ids`	`Sequence[str] \| None`	Keep only the entries with these ids.	`None`
`scope`	`EntryScope \| None`	Keep one kind of entry, e.g. `dash` or `dataset`.	`None`
`scopes`	`Sequence[EntryScope] \| None`	Keep several kinds of entries.	`None`
`type`	`str \| Sequence[str] \| None`	Keep one type of entry, or several (a chart's type, a connection's kind).	`None`
`created_by`	`Sequence[str] \| None`	Keep only what these users created.	`None`
`order_by`	`ListOrder \| None`	What to sort by and in which direction.	`None`
`exclude_locked`	`bool \| None`	Leave out the entries the caller may not read.	`None`
`include_links`	`bool \| None`	Also say what each entry is linked to.	`None`
`filters`	`ListFilters \| None`	Keep the entries whose name has a text.	`None`
`include_permissions_info`	`bool \| None`	Also say what the caller may do with each entry.	`None`
`ignore_workbook_entries`	`bool \| None`	Leave out the entries that lie in workbooks.	`None`
`ignore_shared_entries`	`bool \| None`	Leave out the shared entries.	`None`
`include_data`	`bool \| None`	Also give the content of each entry.	`None`

Returns:

Type	Description
`Listing[Entry]`	The entries found; one the caller may not read comes with `is_locked` set.

Examples:

>>> found = datalens.entries.list(scope="dash", limit=45).collect().items
>>> [(entry.entry_id, entry.key) for entry in found]
[('ent00000000002', 'Sales/overview'), ('ent00000000003', 'Sales/margin')]

relations_list ¶

relations_list(entry_ids: Sequence[str], *, limit: int | None = None, next: str | None = None, link_direction: str | None = None, include_permissions_info: bool | None = None, scope: EntryScope | None = None) -> Listing[Relation]

getEntriesRelations → what entries use, or what uses them, draining the pages.

Capped at limit (None = every relation).

Parameters:

Name	Type	Description	Default
`entry_ids`	`Sequence[str]`	The ids of the entries.	required
`limit`	`int \| None`	The most relations to return; `None` returns every relation.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`
`link_direction`	`str \| None`	`from` lists what the entries use, `to` what uses them.	`None`
`include_permissions_info`	`bool \| None`	Also say what the caller may do with each related entry.	`None`
`scope`	`EntryScope \| None`	Keep one kind of related entry.	`None`

Returns:

Type	Description
`Listing[Relation]`	The related entries.

Examples:

>>> related = datalens.entries.relations_list(["ent00000000002"], link_direction="from")
>>> [relation.entry_id for relation in related]
['ent00000000001']

permissions_get ¶

permissions_get(entry_ids: Sequence[str]) -> EntriesPermissions

getEntriesPermissions → what the caller may do with each entry.

The reply is a map by id: an entry the caller can see gives its permissions, one that does not exist gives error: "NOT_FOUND". An id of a wrong form refuses the whole request (400).

Parameters:

Name	Type	Description	Default
`entry_ids`	`Sequence[str]`	The ids of the entries.	required

Returns:

Type	Description
`EntriesPermissions`	Id → what was found.

Examples:

>>> found = datalens.entries.permissions_get(["ent00000000001", "ent00000000009"])
>>> found.root["ent00000000001"].permissions.read
True
>>> found.root["ent00000000009"].error
'NOT_FOUND'

revisions_list ¶

revisions_list(entry_id: str, *, limit: int | None = None, next: str | None = None, rev_ids: Sequence[str] | None = None) -> Listing[Revision]

getRevisions → the revisions of an entry, draining nextPageToken.

Capped at limit (None = every revision).

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The entry's id.	required
`limit`	`int \| None`	The most revisions to return; `None` returns every revision.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`
`rev_ids`	`Sequence[str] \| None`	Keep only these revisions.	`None`

Returns:

Type	Description
`Listing[Revision]`	The revisions, the newest first.

Examples:

>>> revisions = (
...     datalens.entries.revisions_list("ent00000000001", limit=45).collect().items
... )
>>> [revision.rev_id for revision in revisions]
['rev2', 'rev1']

rename ¶

rename(entry_id: str, *, name: str) -> ItemList[Renamed]

renameEntry — give an entry another name.

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The entry's id.	required
`name`	`str`	The new name.	required

Returns:

Type	Description
`ItemList[Renamed]`	The renamed entry, in a list as the API answers it.

Examples:

>>> datalens.entries.rename("ent00000000001", name="orders 2026").root[0].key
'Sales/orders 2026'

permissions¶

PermissionsClient ¶

PermissionsClient(*, session: SyncSession)

Bases: Resource

Permissions: what the caller may do with entries, workbooks and collections.

get_bulk ¶

get_bulk(*, entry_ids: Sequence[str] | None = None, workbook_ids: Sequence[str] | None = None, collection_ids: Sequence[str] | None = None) -> PermissionsBulk

getPermissionsBulk → the caller's permissions on many objects at once.

Each of the three maps is keyed by id: an object the caller can see gives its permissions, one that does not exist gives error: "NOT_FOUND". An id of a wrong form refuses the whole request (400).

Parameters:

Name	Type	Description	Default
`entry_ids`	`Sequence[str] \| None`	The ids of entries.	`None`
`workbook_ids`	`Sequence[str] \| None`	The ids of workbooks.	`None`
`collection_ids`	`Sequence[str] \| None`	The ids of collections.	`None`

Returns:

Type	Description
`PermissionsBulk`	Three maps, `entries`, `workbooks` and `collections`, id → what was found.

Examples:

>>> found = datalens.permissions.get_bulk(
...     workbook_ids=["wb000000000001", "wb000000000009"]
... )
>>> found.workbooks["wb000000000001"].permissions.update
True
>>> found.workbooks["wb000000000009"].error
'NOT_FOUND'

connections¶

ConnectionsClient ¶

ConnectionsClient(*, session: SyncSession)

Bases: Resource

Connections: where a dataset takes its data from (a database, a file, an API).

get ¶

get(connection_id: str, *, workbook_id: str | None = None, binded_dataset_id: str | None = None, rev_id: str | None = None) -> Connection

getConnection → one connection, without its secrets.

The kind of the connection comes in db_type (the reply has no type), and the fields of that kind come with it as DataLens sends them; a password or a token is never in the reply.

Parameters:

Name	Type	Description	Default
`connection_id`	`str`	The connection's id.	required
`workbook_id`	`str \| None`	The workbook the connection lies in.	`None`
`binded_dataset_id`	`str \| None`	A dataset bound to the connection, to read it through.	`None`
`rev_id`	`str \| None`	The revision to read; the current one when left out.	`None`

Returns:

Type	Description
`Connection`	The connection.

Examples:

>>> connection = datalens.connections.get("con00000000001").root
>>> connection.name, connection.db_type
('Sales DB', 'clickhouse')

create ¶

create(connection: ConnectionCreate) -> ConnectionCreated

createConnection — create a connection → its id.

type says which kind it is and which fields it takes; give workbook_id or dir_path for where it lies. Not every kind can be created through the API: a connection to Google Sheets (gsheets) answers 400 This connection type is not editable. Such a connection is made in the interface and is read here like any other.

Parameters:

Name	Type	Description	Default
`connection`	`ConnectionCreate`	The new connection.	required

Returns:

Type	Description
`ConnectionCreated`	The id of the connection.

Examples:

>>> from ycli.yandex.datalens.connections.models import ConnectionCreate
>>> new = ConnectionCreate.model_validate(
...     {
...         "type": "clickhouse",
...         "name": "Sales DB",
...         "workbook_id": "wb000000000001",
...         "host": "db.example.net",
...         "port": 8443,
...         "username": "reader",
...         "password": "example-password",
...     }
... )
>>> datalens.connections.create(new).id
'con00000000001'

update ¶

update(connection_id: str, *, data: ConnectionUpdate) -> None

updateConnection — change the fields given in data (200, empty body).

Parameters:

Name	Type	Description	Default
`connection_id`	`str`	The connection's id.	required
`data`	`ConnectionUpdate`	The fields to change, of the connection's own kind.	required

Examples:

>>> from ycli.yandex.datalens.connections.models import ConnectionUpdate
>>> change = ConnectionUpdate.model_validate({"host": "db2.example.net"})
>>> datalens.connections.update("con00000000001", data=change)

delete ¶

delete(connection_id: str) -> None

deleteConnection — delete a connection (200, empty body).

The API has no way to bring it back, and a chart that reads through it keeps naming its id (measured).

The interface lists what was deleted under Service settings, Deleted objects, with a Restore button (measured: the entry appears there; restoring was not tried).

The datasets built on it lose their source.

Parameters:

Name	Type	Description	Default
`connection_id`	`str`	The connection's id.	required

Examples:

>>> datalens.connections.delete("con00000000001")

sparkclusters¶

SparkClustersClient ¶

SparkClustersClient(*, session: SyncSession)

Bases: Resource

Spark clusters of DataLens: an experimental API, wrapped by its document, not measured.

A cluster is paid for while it runs. A write answers with an operation that goes on after the reply: ask lakehouseoperations.get for it until done to learn how it ended.

list ¶

list(*, limit: int | None = None, next: str | None = None, collection_id: str | None = None, filter: Sequence[str] | None = None) -> Listing[SparkCluster]

listSparkClusters → the Spark clusters, draining nextPageToken.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	The most clusters to return; `None` returns every cluster.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`
`collection_id`	`str \| None`	Keep the clusters of one collection.	`None`
`filter`	`Sequence[str] \| None`	Filter expressions of the API.	`None`

Returns:

Type	Description
`Listing[SparkCluster]`	The clusters found.

Examples:

>>> [cluster.name for cluster in datalens.sparkclusters.list(limit=45)]
['etl', 'adhoc']

get ¶

get(id: str) -> SparkCluster

getSparkCluster → one Spark cluster: its settings, health and status.

Parameters:

Name	Type	Description	Default
`id`	`str`	The cluster's id.	required

Returns:

Type	Description
`SparkCluster`	The cluster.

Examples:

>>> datalens.sparkclusters.get("sc000000000001").status
'RUNNING'

create ¶

create(*, collection_id: str, cloud_environment_id: str, name: str, config: NewClusterConfig, description: str | None = None, labels: dict[str, str] | None = None) -> LakehouseOperation

createSparkCluster — create a Spark cluster → the operation that creates it.

Parameters:

Name	Type	Description	Default
`collection_id`	`str`	The collection to create the cluster in.	required
`cloud_environment_id`	`str`	The cloud environment the cluster runs in.	required
`name`	`str`	The cluster's name.	required
`config`	`NewClusterConfig`	The Spark version, the pools of the driver and executors, and the rest.	required
`description`	`str \| None`	A description of the cluster.	`None`
`labels`	`dict[str, str] \| None`	Labels of the cluster.	`None`

Returns:

Type	Description
`LakehouseOperation`	The operation; it goes on after the reply.

Examples:

>>> from ycli.yandex.datalens.sparkclusters.models import NewClusterConfig
>>> datalens.sparkclusters.create(
...     collection_id="col00000000001",
...     cloud_environment_id="env00000000001",
...     name="etl",
...     config=NewClusterConfig(sparkVersion="3.5"),
... ).done
False

delete ¶

delete(id: str) -> LakehouseOperation

deleteSparkCluster — delete a Spark cluster → the operation that deletes it.

Parameters:

Name	Type	Description	Default
`id`	`str`	The cluster's id.	required

Returns:

Type	Description
`LakehouseOperation`	The operation; it goes on after the reply.

Examples:

>>> datalens.sparkclusters.delete("sc000000000001").id
'op000000000001'

start ¶

start(cluster_id: str) -> LakehouseOperation

startSparkCluster — start a stopped Spark cluster → the operation.

Parameters:

Name	Type	Description	Default
`cluster_id`	`str`	The cluster's id.	required

Returns:

Type	Description
`LakehouseOperation`	The operation; it goes on after the reply.

Examples:

>>> datalens.sparkclusters.start("sc000000000001").id
'op000000000001'

stop ¶

stop(cluster_id: str) -> LakehouseOperation

stopSparkCluster — stop a running Spark cluster → the operation.

Parameters:

Name	Type	Description	Default
`cluster_id`	`str`	The cluster's id.	required

Returns:

Type	Description
`LakehouseOperation`	The operation; it goes on after the reply.

Examples:

>>> datalens.sparkclusters.stop("sc000000000001").id
'op000000000001'

resource_presets_list ¶

resource_presets_list(cloud_environment_id: str, *, limit: int | None = None, next: str | None = None) -> Listing[SparkResourcePreset]

listSparkResourcePresets → the sizes an instance of a cluster can take.

Parameters:

Name	Type	Description	Default
`cloud_environment_id`	`str`	The cloud environment the presets are for.	required
`limit`	`int \| None`	The most presets to return; `None` returns every preset.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`

Returns:

Type	Description
`Listing[SparkResourcePreset]`	The presets found.

Examples:

>>> found = datalens.sparkclusters.resource_presets_list("env00000000001", limit=45)
>>> [preset.id for preset in found]
['c2-m8', 'c4-m16']

resource_presets_get ¶

resource_presets_get(resource_preset_id: str, *, cloud_environment_id: str) -> SparkResourcePreset

getSparkResourcePreset → one preset: its cores and its memory.

Parameters:

Name	Type	Description	Default
`resource_preset_id`	`str`	The preset's id.	required
`cloud_environment_id`	`str`	The cloud environment the preset is asked for.	required

Returns:

Type	Description
`SparkResourcePreset`	The preset.

Examples:

>>> datalens.sparkclusters.resource_presets_get(
...     "c2-m8", cloud_environment_id="env00000000001"
... ).cores
'2'

htmlpages¶

HTMLPagesClient ¶

HTMLPagesClient(*, session: SyncSession)

Bases: Resource

HTML pages: an entry that holds a page of HTML, shown as it is.

get ¶

get(entry_id: str, *, rev_id: str | None = None, branch: RevisionBranch | None = None, include_permissions: bool | None = None, include_favorite: bool | None = None) -> HTMLPage

getHtmlPage → one HTML page: where it lies and its revisions, not its HTML.

The reply has no content of the page; :meth:preview_url_get gives a link that shows it.

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The page's id.	required
`rev_id`	`str \| None`	One revision to read, as it is; give it or `branch`, not both.	`None`
`branch`	`RevisionBranch \| None`	The version to read when no revision is named: `saved` or `published`.	`None`
`include_permissions`	`bool \| None`	Also say what the caller may do with the page.	`None`
`include_favorite`	`bool \| None`	Also say whether the page is a favourite.	`None`

Returns:

Type	Description
`HTMLPage`	The page.

Examples:

>>> datalens.htmlpages.get("hp000000000001", branch="published").type
'html-page'

create ¶

create(*, content: str, annotation: HTMLPageAnnotation | None = None, key: str | None = None, workbook_id: str | None = None, name: str | None = None) -> HTMLPageCreated

createHtmlPage — create an HTML page → it, with what DataLens warns of.

Creating publishes: the new page's saved and published revisions are the same one (measured). A draft comes with the first update whose mode is save.

Parameters:

Name	Type	Description	Default
`content`	`str`	The HTML of the page.	required
`annotation`	`HTMLPageAnnotation \| None`	A description of the page.	`None`
`key`	`str \| None`	The page's key, in a folder.	`None`
`workbook_id`	`str \| None`	The workbook to create the page in.	`None`
`name`	`str \| None`	The page's name, in a workbook.	`None`

Returns:

Type	Description
`HTMLPageCreated`	The new page under `entry`, and `warnings` about its HTML.

Examples:

>>> made = datalens.htmlpages.create(
...     content="<p>Hello</p>", workbook_id="wb000000000001", name="Hello"
... )
>>> made.warnings
[]

update ¶

update(body: HTMLPageUpdate) -> HTMLPageSaved

updateHtmlPage — save new HTML, or make a revision the current one → the page.

The request is one of two: new content (HTMLPageContent), or a revId to save or publish (HTMLPageRevision). With mode save a new revision is made and the published one stays; publish shows it to everyone. For a revision, save copies it as the current one (measured). The API takes content and revId together and saves the content; ycli refuses the pair, as the document describes none.

Parameters:

Name	Type	Description	Default
`body`	`HTMLPageUpdate`	The new content, or the revision.	required

Returns:

Type	Description
`HTMLPageSaved`	The page under `entry`, and `warnings` about its HTML.

Examples:

>>> from ycli.yandex.datalens.htmlpages.models import HTMLPageUpdate
>>> change = HTMLPageUpdate.model_validate(
...     {"entryId": "hp000000000001", "content": "<p>Bye</p>", "mode": "save"}
... )
>>> datalens.htmlpages.update(change).entry.rev_id
'rev2'

delete ¶

delete(entry_id: str) -> None

deleteHtmlPage — delete an HTML page.

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The page's id.	required

Examples:

>>> datalens.htmlpages.delete("hp000000000001")

preview_url_get ¶

preview_url_get(entry_id: str, *, branch: RevisionBranch | None = None, rev_id: str | None = None, lang: PreviewLanguage | None = None, theme: PreviewTheme | None = None) -> HTMLPagePreview

getHtmlPagePreviewUrl → a temporary signed link that shows the page.

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The page's id.	required
`branch`	`RevisionBranch \| None`	The version to show when no revision is named: `saved` or `published`.	`None`
`rev_id`	`str \| None`	One revision to show, as it is; give it or `branch`, not both.	`None`
`lang`	`PreviewLanguage \| None`	The language of the preview: `en` or `ru`.	`None`
`theme`	`PreviewTheme \| None`	The theme of the preview, e.g. `light` or `dark`.	`None`

Returns:

Type	Description
`HTMLPagePreview`	The link under `url`; it stops working after a while.

Examples:

>>> datalens.htmlpages.preview_url_get("hp000000000001", branch="saved").url
'https://preview.example/hp000000000001?sig=1'

datasets¶

DatasetsClient ¶

DatasetsClient(*, session: SyncSession)

Bases: Resource

Datasets: the fields, sources and joins that charts read their data through.

get ¶

get(dataset_id: str, *, workbook_id: str | None = None, rev_id: str | None = None) -> Dataset

getDataset → one dataset: its sources, their joins and its fields.

A source, a field or an action of a kind this version of ycli does not know is kept as it came (OtherKind…), so the dataset can be changed and sent back whole.

Parameters:

Name	Type	Description	Default
`dataset_id`	`str`	The dataset's id.	required
`workbook_id`	`str \| None`	The workbook the dataset lies in.	`None`
`rev_id`	`str \| None`	The revision to read; the current one when left out.	`None`

Returns:

Type	Description
`Dataset`	The dataset.

Examples:

>>> datalens.datasets.get("ds000000000001").name
'Sales'

create ¶

create(dataset: DatasetContent, *, collection_id: str | None = None, created_via: str | None = None, dir_path: str | None = None, name: str | None = None, options: DatasetOptions | None = None, preview: bool | None = None, published_id: str | None = None, rev_id: str | None = None, saved_id: str | None = None, workbook_id: str | None = None) -> Dataset

createDataset — create a dataset → it, with its id.

A dataset with no source and no field is a valid one: fill it with update.

Parameters:

Name	Type	Description	Default
`dataset`	`DatasetContent`	What the dataset holds: sources, their joins, fields, filters.	required
`collection_id`	`str \| None`	The collection to create it in.	`None`
`created_via`	`str \| None`	How it is created: `user` or `workbook_copy`.	`None`
`dir_path`	`str \| None`	The folder to create it in, where the old placement model is used.	`None`
`name`	`str \| None`	The dataset's name.	`None`
`options`	`DatasetOptions \| None`	What the editor may do with it, as DataLens answers them.	`None`
`preview`	`bool \| None`	Whether the dataset is a preview.	`None`
`published_id`	`str \| None`	The published revision.	`None`
`rev_id`	`str \| None`	The revision.	`None`
`saved_id`	`str \| None`	The saved revision.	`None`
`workbook_id`	`str \| None`	The workbook to create it in.	`None`

Returns:

Type	Description
`Dataset`	The created dataset.

Examples:

>>> from ycli.yandex.datalens.datasets.models import DatasetContent
>>> empty = DatasetContent.model_validate({"sources": [], "result_schema": []})
>>> created = datalens.datasets.create(
...     empty, name="Sales", workbook_id="wb000000000001"
... )
>>> created.id
'ds000000000001'

update ¶

update(dataset_id: str, *, data: DatasetUpdate, workbook_id: str | None = None) -> Dataset

updateDataset — save a dataset as given in data → what was saved.

Read the dataset, change what it holds and send it back whole: data.dataset replaces the content. The reply holds the content and the revisions; its id is null (measured). Read the dataset again after every save: content of an older revision is refused (400 ERR.DS_API.DATASET_REVISION_MISMATCH), by validate too.

Parameters:

Name	Type	Description	Default
`dataset_id`	`str`	The dataset's id.	required
`data`	`DatasetUpdate`	The content to save and how: `mode` is `save` or `publish`.	required
`workbook_id`	`str \| None`	The workbook the dataset lies in.	`None`

Returns:

Type	Description
`Dataset`	The dataset as saved.

Examples:

>>> from ycli.yandex.datalens.datasets.models import DatasetUpdate
>>> change = DatasetUpdate.model_validate({"dataset": {"description": "Q1"}})
>>> datalens.datasets.update("ds000000000001", data=change).rev_id
'rev2'

delete ¶

delete(dataset_id: str) -> None

deleteDataset — delete a dataset (200, empty body).

The API has no way to bring it back, and a chart built on it keeps naming its id (measured).

The interface lists what was deleted under Service settings, Deleted objects, with a Restore button (measured: the entry appears there; restoring was not tried).

The charts built on it lose their data.

Parameters:

Name	Type	Description	Default
`dataset_id`	`str`	The dataset's id.	required

Examples:

>>> datalens.datasets.delete("ds000000000001")

validate ¶

validate(dataset_id: str, *, data: DatasetValidate, workbook_id: str | None = None, binded_dataset_id: str | None = None) -> Dataset

validateDataset → the dataset as it would be, with what is wrong in it.

Nothing is saved. data.updates are the changes to try (add a field, a source), over data.dataset; the reply says code and message and lists dataset_errors.

Parameters:

Name	Type	Description	Default
`dataset_id`	`str`	The dataset's id.	required
`data`	`DatasetValidate`	The content to check and the changes to try on it.	required
`workbook_id`	`str \| None`	The workbook the dataset lies in.	`None`
`binded_dataset_id`	`str \| None`	A dataset bound to this one.	`None`

Returns:

Type	Description
`Dataset`	The checked dataset.

Examples:

>>> from ycli.yandex.datalens.datasets.models import DatasetValidate
>>> tried = DatasetValidate.model_validate({"dataset": {"description": "Q1"}})
>>> datalens.datasets.validate("ds000000000001", data=tried).model_dump()["code"]
'OK'

data_get ¶

data_get(dataset_id: str, *, columns: Sequence[str], workbook_id: str | None = None, filters: Sequence[DataFilter] | None = None, params: Sequence[DataParameter] | None = None, sort: Sequence[DataSort] | None = None, limit: int | None = None, offset: int | None = None) -> DatasetData

getDatasetData → rows of a dataset: the columns asked for, one page.

A column is named by the guid of its field (get lists them in dataset.result_schema), not by its title. One call is one page: limit rows (100 when left out) from offset; an offset above zero needs sort, or the API refuses the request.

Parameters:

Name	Type	Description	Default
`dataset_id`	`str`	The dataset's id.	required
`columns`	`Sequence[str]`	The guids of the fields to return, in the order of the row's values.	required
`workbook_id`	`str \| None`	The workbook the dataset lies in.	`None`
`filters`	`Sequence[DataFilter] \| None`	The rows to keep, by a field's guid, an operation and its values.	`None`
`params`	`Sequence[DataParameter] \| None`	Values for the parameters of the dataset.	`None`
`sort`	`Sequence[DataSort] \| None`	The order of the rows, by a field's guid and a direction.	`None`
`limit`	`int \| None`	The most rows to return.	`None`
`offset`	`int \| None`	How many rows to skip.	`None`

Returns:

Type	Description
`DatasetData`	The columns returned and the rows, each a list of values in that order.

Examples:

>>> page = datalens.datasets.data_get("ds000000000001", columns=["guid-1", "guid-2"])
>>> page.rows
[['Moscow', 120], ['Kazan', 80]]

charts¶

ChartsClient ¶

ChartsClient(*, session: SyncSession)

Bases: Resource

Charts: what a dashboard shows, built in the wizard, in QL or in the editor.

data_get ¶

data_get(chart_id: str, *, params: Mapping[str, str | Sequence[str]] | None = None) -> ChartData

getChartData → the data a saved chart shows, as tables.

The chart runs with its saved settings; params gives the values of its parameters, the page of a table among them. chartType says how the chart is built (wizard, ql, editor), and each table of results has its columns and its rows. A pivot table is not supported (422), and a chart whose source cannot be reached answers 427. A chart of the editor with no source did not answer within the client's wait: the call ends with a timeout after about two minutes (measured, twice).

Parameters:

Name	Type	Description	Default
`chart_id`	`str`	The id of a saved chart.	required
`params`	`Mapping[str, str \| Sequence[str]] \| None`	Values for the chart's parameters, by name: one value or several.	`None`

Returns:

Type	Description
`ChartData`	The tables of the chart.

Examples:

>>> tables = datalens.charts.data_get("ch000000000001").root
>>> tables.chart_type, tables.results[0].rows
('wizard', [['Moscow', 120]])

wizard_get ¶

wizard_get(chart_id: str, *, workbook_id: str | None = None, rev_id: str | None = None, include_permissions: bool | None = None, include_links: bool | None = None, include_favorite: bool | None = None, branch: RevisionBranch | None = None) -> WizardChart

getWizardChart → one chart built in the wizard: its datasets and what it shows.

Parameters:

Name	Type	Description	Default
`chart_id`	`str`	The chart's id.	required
`workbook_id`	`str \| None`	The workbook the chart lies in.	`None`
`rev_id`	`str \| None`	One revision to read, as it is; give it or `branch`, not both.	`None`
`include_permissions`	`bool \| None`	Also say what the caller may do with it.	`None`
`include_links`	`bool \| None`	Also say what it is linked to.	`None`
`include_favorite`	`bool \| None`	Also say whether it is a favourite of the caller.	`None`
`branch`	`RevisionBranch \| None`	The version to read when no revision is named: `saved` or `published`. A save writes the saved one: read `saved` before changing the chart.	`None`

Returns:

Type	Description
`WizardChart`	The chart.

Examples:

>>> chart = datalens.charts.wizard_get("ch000000000001", branch="saved")
>>> chart.entry.entry_id, chart.entry.data.visualization.type
('ch000000000001', 'flatTable')

wizard_create ¶

wizard_create(data: WizardChartData, *, annotation: EntryAnnotation | None = None, key: str | None = None, workbook_id: str | None = None, name: str | None = None) -> WizardChartCreated

createWizardChart — create a chart of the wizard → it, with its id.

Give workbook_id and name for where it lies (key where the old placement model is used). The data of a chart read with wizard_get is a valid one.

Parameters:

Name	Type	Description	Default
`data`	`WizardChartData`	The datasets the chart reads and what it shows.	required
`annotation`	`EntryAnnotation \| None`	A description of the chart.	`None`
`key`	`str \| None`	The entry's key, in a folder.	`None`
`workbook_id`	`str \| None`	The workbook to create it in.	`None`
`name`	`str \| None`	The chart's name.	`None`

Returns:

Type	Description
`WizardChartCreated`	The created chart.

Examples:

>>> from ycli.yandex.datalens.charts.models import WizardChartData
>>> table = {"type": "flatTable", "columns": {"items": [{"guid": "guid-1"}]}}
>>> data = WizardChartData.model_validate(
...     {"sources": {"datasetsIds": ["ds000000000001"]}, "visualization": table}
... )
>>> created = datalens.charts.wizard_create(
...     data, workbook_id="wb000000000001", name="Sales"
... )
>>> created.entry.entry_id
'ch000000000001'

wizard_update ¶

wizard_update(chart_id: str, *, mode: str, data: WizardChartData, annotation: EntryAnnotation | None = None, rev_id: str | None = None) -> WizardChartSaved

updateWizardChart — save a chart of the wizard as given → what was saved.

DataLens does not check a revision here: a save overwrites what was saved since you read it (measured).

data replaces what the chart holds: read it, change it, send it back whole. save keeps the change as a draft (savedId moves, publishedId stays); publish makes it the version everyone sees.

Parameters:

Name	Type	Description	Default
`chart_id`	`str`	The chart's id.	required
`mode`	`str`	`save` or `publish`.	required
`data`	`WizardChartData`	The datasets the chart reads and what it shows.	required
`annotation`	`EntryAnnotation \| None`	A description of the chart.	`None`
`rev_id`	`str \| None`	The revision the change is made on; DataLens does not check it (measured).	`None`

Returns:

Type	Description
`WizardChartSaved`	The chart as saved.

Examples:

>>> from ycli.yandex.datalens.charts.models import WizardChartData
>>> table = {"type": "flatTable", "columns": {"items": [{"guid": "guid-1"}]}}
>>> data = WizardChartData.model_validate(
...     {"sources": {"datasetsIds": ["ds000000000001"]}, "visualization": table}
... )
>>> saved = datalens.charts.wizard_update("ch000000000001", mode="save", data=data)
>>> saved.entry.rev_id
'rev2'

wizard_delete ¶

wizard_delete(chart_id: str) -> None

deleteWizardChart — delete a chart of the wizard; dashboards that show it lose it.

The API has no way to bring it back, and a dashboard that shows it keeps naming its id (measured).

The interface lists what was deleted under Service settings, Deleted objects, with a Restore button (measured: the entry appears there; restoring was not tried).

Parameters:

Name	Type	Description	Default
`chart_id`	`str`	The chart's id.	required

Examples:

>>> datalens.charts.wizard_delete("ch000000000001")

ql_get ¶

ql_get(chart_id: str, *, workbook_id: str | None = None, rev_id: str | None = None, include_permissions: bool | None = None, include_links: bool | None = None, include_favorite: bool | None = None, branch: RevisionBranch | None = None) -> QLChart

getQLChart → one QL chart: flat, with no entry around it.

Parameters:

Name	Type	Description	Default
`chart_id`	`str`	The chart's id.	required
`workbook_id`	`str \| None`	The workbook the chart lies in.	`None`
`rev_id`	`str \| None`	One revision to read, as it is; give it or `branch`, not both.	`None`
`include_permissions`	`bool \| None`	Also say what the caller may do with it.	`None`
`include_links`	`bool \| None`	Also say what it is linked to.	`None`
`include_favorite`	`bool \| None`	Also say whether it is a favourite of the caller.	`None`
`branch`	`RevisionBranch \| None`	The version to read when no revision is named: `saved` or `published`. A save writes the saved one: read `saved` before changing the chart.	`None`

Returns:

Type	Description
`QLChart`	The chart.

Examples:

>>> chart = datalens.charts.ql_get("ch000000000001", branch="saved")
>>> chart.entry_id, chart.type
('ch000000000001', 'table_ql_node')

ql_create ¶

ql_create(*, template: str, data: QLChartData, annotation: EntryAnnotation | None = None, key: str | None = None, workbook_id: str | None = None, name: str | None = None) -> QLChartCreated

createQLChart — create a QL chart → what DataLens answers.

Neither the content of a QL chart nor the reply is described by the specification: data goes as given, the reply is kept as it came.

Parameters:

Name	Type	Description	Default
`template`	`str`	The template of the chart; the API takes only `ql` today.	required
`data`	`QLChartData`	What the chart holds: its query and how it is shown.	required
`annotation`	`EntryAnnotation \| None`	A description of the chart.	`None`
`key`	`str \| None`	The entry's key, in a folder.	`None`
`workbook_id`	`str \| None`	The workbook to create it in.	`None`
`name`	`str \| None`	The chart's name.	`None`

Returns:

Type	Description
`QLChartCreated`	The reply, as it came.

Examples:

>>> from ycli.yandex.datalens.charts.models import QLChartData
>>> data = QLChartData({"queryValue": "select 1"})
>>> created = datalens.charts.ql_create(
...     template="ql", data=data, workbook_id="wb000000000001", name="Top"
... )
>>> created.root["entry"]["entryId"]
'ch000000000001'

ql_update ¶

ql_update(entry_id: str, *, template: str, mode: str, data: QLChartChange, annotation: EntryAnnotation | None = None) -> QLChartSaved

updateQLChart — save a QL chart as given → what DataLens answers.

DataLens does not check a revision here: a save overwrites what was saved since you read it (measured).

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The chart's id.	required
`template`	`str`	The template of the chart; the API takes only `ql` today.	required
`mode`	`str`	`save` or `publish`.	required
`data`	`QLChartChange`	What the chart holds; it replaces the whole of it.	required
`annotation`	`EntryAnnotation \| None`	A description of the chart.	`None`

Returns:

Type	Description
`QLChartSaved`	The reply, as it came.

Examples:

>>> from ycli.yandex.datalens.charts.models import QLChartChange
>>> data = QLChartChange({"queryValue": "select 2"})
>>> saved = datalens.charts.ql_update(
...     "ch000000000001", template="ql", mode="save", data=data
... )
>>> saved.root["entry"]["entryId"]
'ch000000000001'

ql_delete ¶

ql_delete(chart_id: str) -> None

deleteQLChart — delete a QL chart; dashboards that show it lose it.

Parameters:

Name	Type	Description	Default
`chart_id`	`str`	The chart's id.	required

Examples:

>>> datalens.charts.ql_delete("ch000000000001")

editor_get ¶

editor_get(chart_id: str, *, workbook_id: str | None = None, rev_id: str | None = None, include_permissions: bool | None = None, include_links: bool | None = None, include_favorite: bool | None = None, branch: RevisionBranch | None = None) -> EditorChart

getEditorChart → one chart of the editor: its kind (type) and its code.

Parameters:

Name	Type	Description	Default
`chart_id`	`str`	The chart's id.	required
`workbook_id`	`str \| None`	The workbook the chart lies in.	`None`
`rev_id`	`str \| None`	One revision to read, as it is; give it or `branch`, not both.	`None`
`include_permissions`	`bool \| None`	Also say what the caller may do with it.	`None`
`include_links`	`bool \| None`	Also say what it is linked to.	`None`
`include_favorite`	`bool \| None`	Also say whether it is a favourite of the caller.	`None`
`branch`	`RevisionBranch \| None`	The version to read when no revision is named: `saved` or `published`. A save writes the saved one: read `saved` before changing the chart.	`None`

Returns:

Type	Description
`EditorChart`	The chart.

Examples:

>>> chart = datalens.charts.editor_get("ch000000000001", branch="saved")
>>> chart.entry.type
'table_node'

editor_create ¶

editor_create(entry: EditorChartCreate) -> EditorChartCreated

createEditorChart — create a chart of the editor → it, with its id.

type says which kind it is (table_node, d3_node, markdown_node, advanced-chart_node, control_node) and data holds its tabs of code.

Parameters:

Name	Type	Description	Default
`entry`	`EditorChartCreate`	The new chart: where it lies, its kind and its code.	required

Returns:

Type	Description
`EditorChartCreated`	The created chart.

Examples:

>>> from pydantic import TypeAdapter
>>> from ycli.yandex.datalens.charts.models import EditorChartCreate
>>> new = TypeAdapter(EditorChartCreate).validate_python(
...     {"type": "table_node", "workbookId": "wb000000000001", "name": "Top"}
... )
>>> datalens.charts.editor_create(new).entry.type
'table_node'

editor_update ¶

editor_update(entry: EditorChartUpdate, *, mode: str) -> EditorChartSaved

updateEditorChart — save a chart of the editor as given → what was saved.

DataLens does not check a revision here: a save overwrites what was saved since you read it (measured).

Parameters:

Name	Type	Description	Default
`entry`	`EditorChartUpdate`	The chart to save: its `entryId`, its kind and its code.	required
`mode`	`str`	`save` or `publish`.	required

Returns:

Type	Description
`EditorChartSaved`	The chart as saved.

Examples:

>>> from pydantic import TypeAdapter
>>> from ycli.yandex.datalens.charts.models import EditorChartUpdate
>>> change = TypeAdapter(EditorChartUpdate).validate_python(
...     {"type": "table_node", "entryId": "ch000000000001"}
... )
>>> datalens.charts.editor_update(change, mode="save").entry.type
'table_node'

editor_delete ¶

editor_delete(chart_id: str) -> None

deleteEditorChart — delete a chart of the editor; dashboards that show it lose it.

Parameters:

Name	Type	Description	Default
`chart_id`	`str`	The chart's id.	required

Examples:

>>> datalens.charts.editor_delete("ch000000000001")

dashboards¶

DashboardsClient ¶

DashboardsClient(*, session: SyncSession)

Bases: Resource

Dashboards: tabs of charts, selectors and texts.

get ¶

get(dashboard_id: str, *, rev_id: str | None = None, include_permissions: bool | None = None, include_links: bool | None = None, include_favorite: bool | None = None, branch: RevisionBranch | None = None, workbook_id: str | None = None) -> Dashboard

getDashboard → one dashboard: its tabs and what stands on them.

A real dashboard is large: three of the owner's came as 81, 114 and 210 KB.

Parameters:

Name	Type	Description	Default
`dashboard_id`	`str`	The dashboard's id.	required
`rev_id`	`str \| None`	One revision to read, as it is; give it or `branch`, not both.	`None`
`include_permissions`	`bool \| None`	Also say what the caller may do with it.	`None`
`include_links`	`bool \| None`	Also say what it is linked to.	`None`
`include_favorite`	`bool \| None`	Also say whether it is a favourite of the caller.	`None`
`branch`	`RevisionBranch \| None`	The version to read when no revision is named: `saved` or `published`. A save writes the saved one: read `saved` before changing the dashboard.	`None`
`workbook_id`	`str \| None`	The workbook the dashboard lies in.	`None`

Returns:

Type	Description
`Dashboard`	The dashboard.

Examples:

>>> dashboard = datalens.dashboards.get("dash0000000001", branch="saved")
>>> dashboard.entry.entry_id, [tab.title for tab in dashboard.entry.data.tabs]
('dash0000000001', ['Sales'])

create ¶

create(entry: DashboardCreate) -> DashboardCreated

createDashboard — create a dashboard → it, with its id.

entry says where it lies (workbookId and name) and what it holds: data needs counter, salt, settings and tabs, and a tab may be empty. The data of a dashboard read with get is a valid one. entry.meta must be an object, {} when there is nothing to say: without it DataLens answers 400 entry.meta: expected record, received undefined (measured).

Parameters:

Name	Type	Description	Default
`entry`	`DashboardCreate`	The new dashboard: where it lies, its tabs and its settings.	required

Returns:

Type	Description
`DashboardCreated`	The created dashboard.

Examples:

>>> from ycli.yandex.datalens.dashboards.models import DashboardCreate
>>> tab = {"id": "t1", "title": "Sales", "items": [], "layout": []}
>>> new = DashboardCreate.model_validate(
...     {
...         "workbookId": "wb000000000001",
...         "name": "Sales",
...         "data": {"counter": 1, "salt": "s", "settings": {}, "tabs": [tab]},
...     }
... )
>>> datalens.dashboards.create(new).entry.entry_id
'dash0000000001'

update ¶

update(entry: DashboardUpdate, *, mode: str, lock_token: str | None = None) -> DashboardSaved

updateDashboard — save a dashboard as given → what was saved.

DataLens does not check a revision here: a save overwrites what was saved since you read it (measured).

entry names the dashboard by its entryId and replaces what it holds: read it, change data, send it back whole. save keeps a draft, publish makes it the version everyone sees.

Parameters:

Name	Type	Description	Default
`entry`	`DashboardUpdate`	The dashboard to save: its `entryId`, `data`, `meta` and `revId`.	required
`mode`	`str`	`save` or `publish`.	required
`lock_token`	`str \| None`	The token of the lock held on the dashboard, when it is locked.	`None`

Returns:

Type	Description
`DashboardSaved`	The dashboard as saved.

Examples:

>>> from ycli.yandex.datalens.dashboards.models import DashboardUpdate
>>> tab = {"id": "t1", "title": "Sales", "items": [], "layout": []}
>>> change = DashboardUpdate.model_validate(
...     {
...         "entryId": "dash0000000001",
...         "data": {"counter": 2, "salt": "s", "settings": {}, "tabs": [tab]},
...     }
... )
>>> datalens.dashboards.update(change, mode="save").entry.rev_id
'rev2'

delete ¶

delete(dashboard_id: str, *, lock_token: str | None = None) -> None

deleteDashboard — delete a dashboard.

Parameters:

Name	Type	Description	Default
`dashboard_id`	`str`	The dashboard's id.	required
`lock_token`	`str \| None`	The token of the lock held on the dashboard, when it is locked.	`None`

Examples:

>>> datalens.dashboards.delete("dash0000000001")

reports¶

ReportsClient ¶

ReportsClient(*, session: SyncSession)

Bases: Resource

Reports: slides of charts and texts, made to be read and printed.

Measured (2026-10-06): reading is whole, writing is not. A report saved through the API loses the layout of the elements of its slides and part of its settings (create and update alike); DataLens drops them without a word, though ycli sends every value it was given.

get ¶

get(entry_id: str, *, rev_id: str | None = None, include_permissions: bool | None = None, include_favorite: bool | None = None) -> Report

getReport → one report: its slides and what stands on them.

A report has no branch in the API: the read answers the saved version (measured).

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The report's id.	required
`rev_id`	`str \| None`	The revision to read; the current one when left out.	`None`
`include_permissions`	`bool \| None`	Also say what the caller may do with it.	`None`
`include_favorite`	`bool \| None`	Also say whether it is a favourite of the caller.	`None`

Returns:

Type	Description
`Report`	The report.

Examples:

>>> datalens.reports.get("rep00000000001").entry.entry_id
'rep00000000001'

create ¶

create(*, data: ReportData, meta: ReportMeta | None, annotation: EntryAnnotation | None = None, include_permissions: bool | None = None, key: str | None = None, workbook_id: str | None = None, name: str | None = None) -> ReportCreated

createReport — create a report → it, with its id.

Measured (2026-10-06): a report saved through the API loses the layout of the elements of its slides and part of its settings; DataLens drops them without a word. A copy made from the data of a report read with get is valid, and has lost where its elements stood.

Give workbook_id and name for where it lies (key where the old placement model is used).

Parameters:

Name	Type	Description	Default
`data`	`ReportData`	What the report holds: its slides and its settings.	required
`meta`	`ReportMeta \| None`	Metadata of the entry; `None` for none.	required
`annotation`	`EntryAnnotation \| None`	A description of the report.	`None`
`include_permissions`	`bool \| None`	Also say what the caller may do with the new report.	`None`
`key`	`str \| None`	The entry's key, in a folder.	`None`
`workbook_id`	`str \| None`	The workbook to create it in.	`None`
`name`	`str \| None`	The report's name.	`None`

Returns:

Type	Description
`ReportCreated`	The created report.

Examples:

>>> from ycli.yandex.datalens.reports.models import ReportData
>>> data = ReportData.model_validate({"slides": [{"id": "s1"}]})
>>> created = datalens.reports.create(
...     data=data, meta=None, workbook_id="wb000000000001", name="Q1"
... )
>>> created.entry.entry_id
'rep00000000001'

update ¶

update(entry_id: str, *, data: ReportData, mode: str, meta: ReportMeta | None, rev_id: str | None = None, annotation: EntryAnnotation | None = None) -> ReportSaved

updateReport — save a report as given → what was saved.

DataLens does not check a revision here: a save overwrites what was saved since you read it (measured).

Measured (2026-10-06): a report saved through the API loses the layout of the elements of its slides and part of its settings; DataLens drops them without a word. So do not save a report that exists without telling its owner what it will lose.

data replaces what the report holds: read it, change it, send it back whole.

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The report's id.	required
`data`	`ReportData`	What the report holds.	required
`mode`	`str`	`save` or `publish`.	required
`meta`	`ReportMeta \| None`	Metadata of the entry; `None` for none.	required
`rev_id`	`str \| None`	The revision the change is made on; DataLens does not check it (measured).	`None`
`annotation`	`EntryAnnotation \| None`	A description of the report.	`None`

Returns:

Type	Description
`ReportSaved`	The report as saved.

Examples:

>>> from ycli.yandex.datalens.reports.models import ReportData
>>> data = ReportData.model_validate({"slides": [{"id": "s1"}, {"id": "s2"}]})
>>> saved = datalens.reports.update("rep00000000001", data=data, mode="save", meta=None)
>>> saved.entry.rev_id
'rev2'

delete ¶

delete(entry_id: str) -> None

deleteReport — delete a report.

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The report's id.	required

Examples:

>>> datalens.reports.delete("rep00000000001")

workbookexports¶

WorkbookExportsClient ¶

WorkbookExportsClient(*, session: SyncSession)

Bases: Resource

Exports of a workbook: everything it holds as one document, to import elsewhere.

start ¶

start(workbook_id: str) -> WorkbookExportStarted

startWorkbookExport — start exporting a workbook → the id of the export.

The export runs on its own: ask :meth:status_get until it is over, then :meth:result_get for the document.

Parameters:

Name	Type	Description	Default
`workbook_id`	`str`	The workbook's id.	required

Returns:

Type	Description
`WorkbookExportStarted`	The id of the export.

Examples:

>>> datalens.workbookexports.start("wb000000000001").export_id
'exp0000000001'

status_get ¶

status_get(export_id: str) -> WorkbookExportStatus

getWorkbookExportStatus → how far an export is.

status is pending, success or error; notifications holds what the export has to say about an entry: its id, a level and a message.

Parameters:

Name	Type	Description	Default
`export_id`	`str`	The export's id.	required

Returns:

Type	Description
`WorkbookExportStatus`	The status, the progress in percent and the notifications.

Examples:

>>> state = datalens.workbookexports.status_get("exp0000000001")
>>> state.status.root, state.progress
('success', 100)

result_get ¶

result_get(export_id: str) -> WorkbookExport

getWorkbookExportResult → the exported workbook.

data is what :meth:WorkbookImportsClient.start takes. An export that is not over, or was cancelled, answers 409 Conflict. The document is large (hundreds of kilobytes for a workbook with a dashboard) and holds no password or token of a connection.

Parameters:

Name	Type	Description	Default
`export_id`	`str`	The export's id.	required

Returns:

Type	Description
`WorkbookExport`	The export: `data.export` holds the entries of the workbook, `data.hash` its
`WorkbookExport`	checksum.

Examples:

>>> exported = datalens.workbookexports.result_get("exp0000000001")
>>> sorted(exported.data.export)
['entries', 'version']

cancel ¶

cancel(export_id: str) -> WorkbookExportCancelled

cancelWorkbookExport — stop an export → its id.

A cancelled export ends with the status error and the notification WORKBOOK_EXPORT_CANCELLED. An export that is over stays as it ended, and the call answers the same.

Parameters:

Name	Type	Description	Default
`export_id`	`str`	The export's id.	required

Returns:

Type	Description
`WorkbookExportCancelled`	The id of the export.

Examples:

>>> datalens.workbookexports.cancel("exp0000000002").export_id
'exp0000000002'

workbookimports¶

WorkbookImportsClient ¶

WorkbookImportsClient(*, session: SyncSession)

Bases: Resource

Imports of a workbook: a new workbook made from the document an export gave.

start ¶

start(data: dict[str, Any], *, title: str, collection_id: str | None = None, description: str | None = None) -> WorkbookImportStarted

startWorkbookImport — start making a workbook from an export → its ids.

The workbook exists at once and is filled as the import runs: ask :meth:status_get until it is over. Its connections come without their secrets (a notification …CONN.CHECK_CREDENTIALS says so) and take them again through an update.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	The `data` of an export's result: its `export` and its `hash`.	required
`title`	`str`	The title of the new workbook.	required
`collection_id`	`str \| None`	The collection to make it in; the root when left out.	`None`
`description`	`str \| None`	The description of the new workbook.	`None`

Returns:

Type	Description
`WorkbookImportStarted`	The id of the import and the id of the new workbook.

Examples:

>>> exported = {"export": {"version": "1", "entries": {}}, "hash": "h1"}
>>> started = datalens.workbookimports.start(
...     exported, title="Sales, copy", collection_id="col0000000001"
... )
>>> started.import_id, started.workbook_id
('imp0000000001', 'wb000000000002')

status_get ¶

status_get(import_id: str) -> WorkbookImportStatus

getWorkbookImportStatus → how far an import is.

status is pending, success or error; notifications holds what the import has to say about an entry: its id, a level and a message.

Parameters:

Name	Type	Description	Default
`import_id`	`str`	The import's id.	required

Returns:

Type	Description
`WorkbookImportStatus`	The status, the progress in percent and the id of the workbook.

Examples:

>>> state = datalens.workbookimports.status_get("imp0000000001")
>>> state.status.root, state.workbook_id
('success', 'wb000000000002')

embeds¶

EmbedsClient ¶

EmbedsClient(*, session: SyncSession)

Bases: Resource

Embeds: a chart or a dashboard shown on another site, signed with a key for embedding.

list ¶

list(entry_id: str) -> ItemList[Embed]

listEmbeds → the embeds of one entry.

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The id of the entry that is embedded.	required

Returns:

Type	Description
`ItemList[Embed]`	The embeds of the entry.

Examples:

>>> [embed.title for embed in datalens.embeds.list("ent0000000001").root]
['Sales on the portal']

create ¶

create(*, title: str, embedding_secret_id: str, entry_id: str, public_params_mode: bool, settings: EmbedSettings, deps_ids: Sequence[str] = (), unsigned_params: Sequence[str] = (), private_params: Sequence[str] = ()) -> Embed

createEmbed — embed an entry → the embed.

Parameters:

Name	Type	Description	Default
`title`	`str`	The name of the embed.	required
`embedding_secret_id`	`str`	The key for embedding that signs its links.	required
`entry_id`	`str`	The entry to embed.	required
`public_params_mode`	`bool`	Whether the default mode of parameters is on.	required
`settings`	`EmbedSettings`	The settings of the embed; an empty one is valid.	required
`deps_ids`	`Sequence[str]`	The entries the embedded one depends on.	`()`
`unsigned_params`	`Sequence[str]`	The parameters a link may carry unsigned.	`()`
`private_params`	`Sequence[str]`	The parameters that go signed, inside the token.	`()`

Returns:

Type	Description
`Embed`	The embed.

Examples:

>>> from ycli.yandex.datalens.embeds.models import EmbedSettings
>>> embed = datalens.embeds.create(
...     title="Sales on the portal",
...     embedding_secret_id="sec0000000001",
...     entry_id="ent0000000001",
...     public_params_mode=True,
...     settings=EmbedSettings(),
... )
>>> embed.embed_id
'emb0000000001'

update ¶

update(embed_id: str, *, title: str, embedding_secret_id: str, public_params_mode: bool, settings: EmbedSettings, deps_ids: Sequence[str] = (), unsigned_params: Sequence[str] = (), private_params: Sequence[str] = ()) -> Embed

updateEmbed — save an embed as given → the embed.

The embed is replaced whole: the API requires every field, so read the embed with :meth:list and send back what is to stay.

Parameters:

Name	Type	Description	Default
`embed_id`	`str`	The embed's id.	required
`title`	`str`	The name of the embed.	required
`embedding_secret_id`	`str`	The key for embedding that signs its links.	required
`public_params_mode`	`bool`	Whether the default mode of parameters is on.	required
`settings`	`EmbedSettings`	The settings of the embed; an empty one is valid.	required
`deps_ids`	`Sequence[str]`	The entries the embedded one depends on.	`()`
`unsigned_params`	`Sequence[str]`	The parameters a link may carry unsigned.	`()`
`private_params`	`Sequence[str]`	The parameters that go signed, inside the token.	`()`

Returns:

Type	Description
`Embed`	The embed as saved.

Examples:

>>> from ycli.yandex.datalens.embeds.models import EmbedSettings
>>> embed = datalens.embeds.update(
...     "emb0000000001",
...     title="Sales, renamed",
...     embedding_secret_id="sec0000000001",
...     public_params_mode=False,
...     settings=EmbedSettings.model_validate({"enableExport": True}),
...     unsigned_params=["region"],
... )
>>> embed.title
'Sales, renamed'

delete ¶

delete(embed_id: str) -> EmbedDeleted

deleteEmbed — delete an embed → its id.

Its links stop working. Deleting again answers 404.

Parameters:

Name	Type	Description	Default
`embed_id`	`str`	The embed's id.	required

Returns:

Type	Description
`EmbedDeleted`	The id of the deleted embed.

Examples:

>>> datalens.embeds.delete("emb0000000001").embed_id
'emb0000000001'

embeddingsecrets¶

EmbeddingSecretsClient ¶

EmbeddingSecretsClient(*, session: SyncSession)

Bases: Resource

Keys for embedding: a workbook's key pairs that sign the links of its embeds.

get ¶

get(embedding_secret_id: str) -> EmbeddingSecret

getEmbeddingSecret → one key for embedding, without its private key.

Parameters:

Name	Type	Description	Default
`embedding_secret_id`	`str`	The key's id.	required

Returns:

Type	Description
`EmbeddingSecret`	The key's name, its workbook, and who made it when.

Examples:

>>> datalens.embeddingsecrets.get("sec0000000001").title
'Portal key'

list ¶

list(workbook_id: str) -> ItemList[EmbeddingSecret]

listEmbeddingSecrets → the keys for embedding of a workbook, without private keys.

Parameters:

Name	Type	Description	Default
`workbook_id`	`str`	The workbook's id.	required

Returns:

Type	Description
`ItemList[EmbeddingSecret]`	The keys of the workbook.

Examples:

>>> keys = datalens.embeddingsecrets.list("wb000000000001").root
>>> [key.embedding_secret_id for key in keys]
['sec0000000001']

create ¶

create(*, title: str, workbook_id: str) -> EmbeddingSecretCreated

createEmbeddingSecret — make a key for embedding → its id and its private key.

The private key is given once, here: :meth:get and :meth:list do not return it, so keep it at once.

Parameters:

Name	Type	Description	Default
`title`	`str`	The name of the key.	required
`workbook_id`	`str`	The workbook the key belongs to.	required

Returns:

Type	Description
`EmbeddingSecretCreated`	The id of the key and its private key.

Examples:

>>> made = datalens.embeddingsecrets.create(
...     title="Portal key", workbook_id="wb000000000001"
... )
>>> made.embedding_secret_id, made.private_key
('sec0000000001', 'example-private-key')

delete ¶

delete(embedding_secret_id: str) -> EmbeddingSecretDeleted

deleteEmbeddingSecret — delete a key for embedding → its id.

Deleting again answers 404.

Parameters:

Name	Type	Description	Default
`embedding_secret_id`	`str`	The key's id.	required

Returns:

Type	Description
`EmbeddingSecretDeleted`	The id of the deleted key.

Examples:

>>> datalens.embeddingsecrets.delete("sec0000000001").embedding_secret_id
'sec0000000001'

sharedentries¶

SharedEntriesClient ¶

SharedEntriesClient(*, session: SyncSession)

Bases: Resource

Shared entries: a connection or a dataset that lies in a collection, not in a workbook.

access_bindings_list ¶

access_bindings_list(entry_id: str, *, limit: int | None = None, next: str | None = None, get_inherited_bindings: bool | None = None) -> Listing[SubjectWithBindings]

listSharedEntryAccessBindings → who has which role, draining nextPageToken.

Capped at limit (None = every subject). An entry that lies in a workbook, or an id nothing knows, answers an empty list, not an error.

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The shared entry's id.	required
`limit`	`int \| None`	The most subjects to return; `None` returns every subject.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`
`get_inherited_bindings`	`bool \| None`	Also list the roles inherited from the collections above.	`None`

Returns:

Type	Description
`Listing[SubjectWithBindings]`	The subjects with their roles.

Examples:

>>> subjects = (
...     datalens.sharedentries.access_bindings_list("ent0000000001").collect().items
... )
>>> subjects[0].access_bindings[0].role_id
'datalens.sharedEntries.admin'

access_bindings_update ¶

access_bindings_update(entry_id: str, *, deltas: Sequence[AccessBindingDelta]) -> Operation

updateSharedEntryAccessBindings — give or take away roles on a shared entry.

Each delta adds (ADD) or removes (REMOVE) one role of one subject; the roles not named stay as they are. The roles are datalens.sharedEntries.*.

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The shared entry's id.	required
`deltas`	`Sequence[AccessBindingDelta]`	The roles to add and to remove.	required

Returns:

Type	Description
`Operation`	The operation that applies the change.

Examples:

>>> from ycli.yandex.datalens.models import AccessBindingDelta
>>> delta = AccessBindingDelta.model_validate(
...     {
...         "action": "ADD",
...         "accessBinding": {
...             "roleId": "datalens.sharedEntries.viewer",
...             "subject": {"id": "user-2", "type": "userAccount"},
...         },
...     }
... )
>>> datalens.sharedentries.access_bindings_update("ent0000000001", deltas=[delta]).done
True

audit¶

AuditClient ¶

AuditClient(*, session: SyncSession)

Bases: Resource

Audit: which entries changed and when, and what one user may do with an entry.

entries_updates_list ¶

entries_updates_list(from_: str, *, to: str | None = None, limit: int | None = None, next: str | None = None) -> Listing[AuditEntry]

getAuditEntriesUpdates → the entries changed in a period, draining the pages.

Capped at limit (None = every entry). A deleted entry is listed too, with is_deleted.

Parameters:

Name	Type	Description	Default
`from_`	`str`	The start of the period, an ISO-8601 time with its zone.	required
`to`	`str \| None`	The end of the period.	`None`
`limit`	`int \| None`	The most entries to return; `None` returns every entry.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`

Returns:

Type	Description
`Listing[AuditEntry]`	The entries changed in the period: what each is, when it changed and who did it.

Examples:

>>> changed = (
...     datalens.audit.entries_updates_list("2026-10-01T00:00:00Z").collect().items
... )
>>> [(entry.entry_id, entry.is_deleted) for entry in changed]
[('ent0000000001', False), ('ent0000000002', True)]

entry_permissions_get ¶

entry_permissions_get(entry_ids: Sequence[str], *, user_id: str) -> UserEntryPermissions

getAuditEntryPermissionsForUser → what one user may do with each entry.

Parameters:

Name	Type	Description	Default
`entry_ids`	`Sequence[str]`	The ids of the entries to ask about.	required
`user_id`	`str`	The user's id, as `createdBy` of an entry gives it.	required

Returns:

Type	Description
`UserEntryPermissions`	By entry id: `permissions` (execute, read, edit, admin), or `error` for an entry
`UserEntryPermissions`	that does not exist.

Examples:

>>> answer = datalens.audit.entry_permissions_get(
...     ["ent0000000001"], user_id="user-1"
... ).root
>>> answer["ent0000000001"].permissions.edit
True

sqlqueries¶

SqlQueriesClient ¶

SqlQueriesClient(*, session: SyncSession)

Bases: Resource

Saved SQL queries: a text of SQL kept in a workbook and run over a connection.

Experimental in the DataLens API, and written from its document: no reply was measured. An organization whose SQL editor is off answers 403 SQL_EDITOR_NOT_ALLOWED.

get ¶

get(sql_query_id: str, *, rev_id: str | None = None, include_permissions: bool | None = None, include_favorite: bool | None = None) -> SqlQueryDetails

getSqlQuery → one saved SQL query (experimental, not measured).

Parameters:

Name	Type	Description	Default
`sql_query_id`	`str`	The query's id.	required
`rev_id`	`str \| None`	The revision to read; the current one when left out.	`None`
`include_permissions`	`bool \| None`	Also say what the caller may do with it.	`None`
`include_favorite`	`bool \| None`	Also say whether it is a favourite.	`None`

Returns:

Type	Description
`SqlQueryDetails`	The query: `entry.data` holds its text, its connection and its parameters.

Examples:

>>> found = datalens.sqlqueries.get("sq00000000001").entry
>>> found.data.query
'select count(*) from orders where day >= {{since}}'

create ¶

create(*, workbook_id: str, name: str, connection_id: str, query: str, description: str | None = None, params: Sequence[SqlQueryNewParam] | None = None) -> SqlQueryCreated

createSqlQuery — save a SQL query in a workbook (experimental, not measured).

Parameters:

Name	Type	Description	Default
`workbook_id`	`str`	The workbook to keep it in.	required
`name`	`str`	The query's name in the workbook.	required
`connection_id`	`str`	The connection it runs over: PostgreSQL, ClickHouse, MySQL, Greenplum or Trino.	required
`query`	`str`	The text of the query.	required
`description`	`str \| None`	A description.	`None`
`params`	`Sequence[SqlQueryNewParam] \| None`	The parameters the text takes, each with a name, a type and a default.	`None`

Returns:

Type	Description
`SqlQueryCreated`	The query as saved.

Examples:

>>> made = datalens.sqlqueries.create(
...     workbook_id="wb000000000001",
...     name="Orders a day",
...     connection_id="con00000000001",
...     query="select count(*) from orders",
... )
>>> made.entry.entry_id
'sq00000000001'

update ¶

update(sql_query_id: str, *, connection_id: str, query: str, description: str | None = None, params: Sequence[SqlQuerySavedParam] | None = None) -> SqlQuerySaved

updateSqlQuery — save a SQL query anew (experimental, not measured).

The document requires the connection and the text every time.

Parameters:

Name	Type	Description	Default
`sql_query_id`	`str`	The query's id.	required
`connection_id`	`str`	The connection it runs over.	required
`query`	`str`	The text of the query.	required
`description`	`str \| None`	A new description.	`None`
`params`	`Sequence[SqlQuerySavedParam] \| None`	The parameters the text takes.	`None`

Returns:

Type	Description
`SqlQuerySaved`	The query as saved.

Examples:

>>> saved = datalens.sqlqueries.update(
...     "sq00000000001",
...     connection_id="con00000000001",
...     query="select count(*) from orders where paid",
... )
>>> saved.entry.data.query
'select count(*) from orders where paid'

delete ¶

delete(sql_query_id: str) -> None

deleteSqlQuery — delete a saved SQL query (experimental, not measured).

Parameters:

Name	Type	Description	Default
`sql_query_id`	`str`	The query's id.	required

Examples:

>>> datalens.sqlqueries.delete("sq00000000001")

run ¶

run(sql_query_id: str, *, params: Mapping[str, SqlQueryValue] | None = None) -> SqlQueryRun

runSqlQuery — run a saved SQL query → its result (experimental, not measured).

The query runs on its connection as it is saved: a text that changes data changes it. A parameter left out takes its default.

Parameters:

Name	Type	Description	Default
`sql_query_id`	`str`	The query's id.	required
`params`	`Mapping[str, SqlQueryValue] \| None`	The values of the parameters, by name.	`None`

Returns:

Type	Description
`SqlQueryRun`	The run: its `status` and, for each statement, the columns and the rows, or the
`SqlQueryRun`	error.

Examples:

>>> ran = datalens.sqlqueries.run("sq00000000001", params={"since": "2026-10-01"})
>>> ran.status, ran.results[0].rows
('success', [[42]])

licensing¶

LicensingClient ¶

LicensingClient(*, session: SyncSession)

Bases: Resource

Licences: the seats of the DataLens instance, who holds one, and how many there may be.

A licence is a seat, and DataLens bills for seats (its pricing: the number of seats times the cost of one). The two writes here change that number and were never called: they are written from the document, not measured.

licenses_list ¶

licenses_list(*, user_ids: Sequence[str] | None = None, status: LicenseStatus | None = None, sort_by: LicenseSortField | None = None, order: SortDirection | None = None, limit: int | None = None, next: str | None = None) -> Listing[LicenseListed]

getLicenses → the licences of the instance, draining the pages.

Capped at limit (None = every licence).

Parameters:

Name	Type	Description	Default
`user_ids`	`Sequence[str] \| None`	Only the licences of these users.	`None`
`status`	`LicenseStatus \| None`	Only the licences in this state: `active`, `expired` or `expiring`.	`None`
`sort_by`	`LicenseSortField \| None`	The field to sort by: `createdAt` or `updatedAt`.	`None`
`order`	`SortDirection \| None`	`asc` or `desc`.	`None`
`limit`	`int \| None`	The most licences to return; `None` returns every licence.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`

Returns:

Type	Description
`Listing[LicenseListed]`	The licences: whose each is, its type, whether it is active and when its holder
`Listing[LicenseListed]`	last signed in.

Examples:

>>> held = datalens.licensing.licenses_list(status="active").collect().items
>>> [(licence.user_id, licence.license_type) for licence in held]
[('user-1', 'creator')]

licenses_assign ¶

licenses_assign(user_ids: Sequence[str]) -> ItemList[License]

assignLicenses — give each of these users a licence (not measured).

A licence is a seat DataLens bills for. Written from the document: never called.

Parameters:

Name	Type	Description	Default
`user_ids`	`Sequence[str]`	The users to give a licence to.	required

Returns:

Type	Description
`ItemList[License]`	The licences given.

Examples:

>>> given = datalens.licensing.licenses_assign(["user-2"]).root
>>> given[0].user_id
'user-2'

limit_get ¶

limit_get() -> LicenseLimits

getLicensesLimit → how many licences the instance may hold, now and next.

Returns:

Type	Description
`LicenseLimits`	`current`: the limit in force, with the count of active licences; `next`: the
`LicenseLimits`	limit that takes over later, or `None`.

Examples:

>>> limits = datalens.licensing.limit_get()
>>> limits.current.value, limits.current.active_licenses_count
(1, 1)

limit_set ¶

limit_set(value: int) -> LicenseLimits

setLicenseLimit — set how many licences the instance may hold (not measured).

The limit is the number of seats DataLens bills for. Written from the document: never called.

Parameters:

Name	Type	Description	Default
`value`	`int`	The most licences the instance may hold.	required

Returns:

Type	Description
`LicenseLimits`	The limits after the change.

Examples:

>>> datalens.licensing.limit_set(3).current.value
3

cloudenvironments¶

CloudEnvironmentsClient ¶

CloudEnvironmentsClient(*, session: SyncSession)

Bases: Resource

Cloud environments: a cloud and a subnet DataLens runs clusters in, with a bucket.

Experimental in the DataLens API. Listing is measured; the rest is written from the document: making, changing and deleting an environment creates cloud resources and was never called.

list ¶

list(*, filter: Sequence[str] | None = None, include_permissions: bool | None = None, limit: int | None = None, next: str | None = None) -> Listing[CloudEnvironment]

listCloudEnvironments → the cloud environments, draining nextPageToken.

Capped at limit (None = every environment).

Parameters:

Name	Type	Description	Default
`filter`	`Sequence[str] \| None`	Conditions, all of which must hold; each is `field="value"` over `name`, `cloud_id`, `status` or `created_by_id`.	`None`
`include_permissions`	`bool \| None`	Also say what the caller may do with each one.	`None`
`limit`	`int \| None`	The most environments to return; `None` returns every one.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`

Returns:

Type	Description
`Listing[CloudEnvironment]`	The cloud environments.

Examples:

>>> found = datalens.cloudenvironments.list(filter=['status="READY"']).collect().items
>>> [(environment.id, environment.status) for environment in found]
[('env0000000001', 'READY')]

get ¶

get(id: str, *, include_permissions: bool | None = None) -> CloudEnvironment

getCloudEnvironment → one cloud environment (not measured).

An id nothing knows answers 403 Permission denied, not 404.

Parameters:

Name	Type	Description	Default
`id`	`str`	The environment's id.	required
`include_permissions`	`bool \| None`	Also say what the caller may do with it.	`None`

Returns:

Type	Description
`CloudEnvironment`	The environment: its cloud, its subnet, its status and its storage.

Examples:

>>> datalens.cloudenvironments.get("env0000000001").name
'Analytics'

create ¶

create(*, name: str, cloud_id: str, subnet_id: str, description: str | None = None, security_group_ids: Sequence[str] | None = None, storage: CloudEnvironmentNewStorage | None = None) -> LakehouseOperation

createCloudEnvironment — make a cloud environment (not measured, never called).

It creates resources in a cloud, which may be billed. The reply is an operation: ask getLakehouseOperation for it until done.

Parameters:

Name	Type	Description	Default
`name`	`str`	The environment's name.	required
`cloud_id`	`str`	The cloud to make it in.	required
`subnet_id`	`str`	The subnet it uses.	required
`description`	`str \| None`	A description.	`None`
`security_group_ids`	`Sequence[str] \| None`	The security groups it uses.	`None`
`storage`	`CloudEnvironmentNewStorage \| None`	The settings of its storage bucket; no bucket when left out.	`None`

Returns:

Type	Description
`LakehouseOperation`	The operation that makes it.

Examples:

>>> started = datalens.cloudenvironments.create(
...     name="Analytics", cloud_id="b1g00000000000000001", subnet_id="e9b0000000001"
... )
>>> started.id, started.done
('op0000000000001', False)

update ¶

update(id: str, *, name: str | None = None, description: str | None = None, security_group_ids: Sequence[str] | None = None, storage: CloudEnvironmentStorageChange | None = None) -> LakehouseOperation

updateCloudEnvironment — change the fields given (not measured, never called).

The cloud and the subnet cannot change. An empty description clears it.

Parameters:

Name	Type	Description	Default
`id`	`str`	The environment's id.	required
`name`	`str \| None`	A new name.	`None`
`description`	`str \| None`	A new description.	`None`
`security_group_ids`	`Sequence[str] \| None`	The security groups it is to use.	`None`
`storage`	`CloudEnvironmentStorageChange \| None`	New settings of its storage bucket.	`None`

Returns:

Type	Description
`LakehouseOperation`	The operation that changes it.

Examples:

>>> datalens.cloudenvironments.update("env0000000001", name="Analytics, EU").id
'op0000000000002'

delete ¶

delete(id: str) -> LakehouseOperation

deleteCloudEnvironment — delete a cloud environment (not measured, never called).

Parameters:

Name	Type	Description	Default
`id`	`str`	The environment's id.	required

Returns:

Type	Description
`LakehouseOperation`	The operation that deletes it.

Examples:

>>> datalens.cloudenvironments.delete("env0000000001").id
'op0000000000003'

cloudenvironmentstorage¶

CloudEnvironmentStorageClient ¶

CloudEnvironmentStorageClient(*, session: SyncSession)

Bases: Resource

The storage bucket of a cloud environment: its objects, and links to read and write one.

Experimental in the DataLens API and written from its document: the owner's instance has no cloud environment, so no reply was measured. An environment nothing knows answers 403 Permission denied.

bucket_objects_list ¶

bucket_objects_list(cloud_environment_id: str, *, prefix: str | None = None, limit: int | None = None, next: str | None = None) -> Listing[str]

listBucketObjects → the paths of the objects in the bucket (not measured).

Capped at limit (None = every path).

Parameters:

Name	Type	Description	Default
`cloud_environment_id`	`str`	The environment the bucket belongs to.	required
`prefix`	`str \| None`	Only the paths that start with this.	`None`
`limit`	`int \| None`	The most paths to return; `None` returns every path.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`

Returns:

Type	Description
`Listing[str]`	The paths of the objects.

Examples:

>>> datalens.cloudenvironmentstorage.bucket_objects_list(
...     "env0000000001", prefix="raw/"
... ).collect().items
['raw/orders.parquet', 'raw/users.parquet']

bucket_object_metadata_get ¶

bucket_object_metadata_get(cloud_environment_id: str, *, path: str) -> BucketObjectMetadata

getBucketObjectMetadata → the size of an object and when it changed (not measured).

Parameters:

Name	Type	Description	Default
`cloud_environment_id`	`str`	The environment the bucket belongs to.	required
`path`	`str`	The path of the object in the bucket.	required

Returns:

Type	Description
`BucketObjectMetadata`	The size in bytes, as a string, and the time of the last change.

Examples:

>>> datalens.cloudenvironmentstorage.bucket_object_metadata_get(
...     "env0000000001", path="raw/orders.parquet"
... ).size
'1048576'

bucket_download_url_create ¶

bucket_download_url_create(cloud_environment_id: str, *, path: str) -> BucketDownloadUrl

createBucketDownloadUrl → a signed link to read one object (not measured).

The link works for whoever holds it, for a time: treat it as a secret.

Parameters:

Name	Type	Description	Default
`cloud_environment_id`	`str`	The environment the bucket belongs to.	required
`path`	`str`	The path of the object in the bucket.	required

Returns:

Type	Description
`BucketDownloadUrl`	The link.

Examples:

>>> datalens.cloudenvironmentstorage.bucket_download_url_create(
...     "env0000000001", path="raw/orders.parquet"
... ).url
'https://storage.example.net/raw/orders.parquet?signature=example'

bucket_upload_url_create ¶

bucket_upload_url_create(cloud_environment_id: str, *, path: str, size: str, content_md5: str) -> BucketUploadUrl

createBucketUploadUrl → a signed link to put one object (not measured).

The link works for whoever holds it, for a time: treat it as a secret.

Parameters:

Name	Type	Description	Default
`cloud_environment_id`	`str`	The environment the bucket belongs to.	required
`path`	`str`	The path the object is to have in the bucket.	required
`size`	`str`	The size of the object in bytes, as a string.	required
`content_md5`	`str`	The MD5 digest of the content: 16 bytes, base64-encoded.	required

Returns:

Type	Description
`BucketUploadUrl`	The link.

Examples:

>>> datalens.cloudenvironmentstorage.bucket_upload_url_create(
...     "env0000000001",
...     path="raw/new.parquet",
...     size="2048",
...     content_md5="1B2M2Y8AsgTpgAmY7PhCfg==",
... ).url
'https://storage.example.net/raw/new.parquet?signature=example'

restcatalogs¶

RestCatalogsClient ¶

RestCatalogsClient(*, session: SyncSession)

Bases: Resource

REST catalogs: a catalog of tables with a bucket of its own, in a cloud environment.

Experimental in the DataLens API. Listing is measured; making a catalog creates a bucket in a cloud and was never called: it is written from the document.

list ¶

list(*, cloud_environment_id: str | None = None, filter: Sequence[str] | None = None, sort_by: RestCatalogSortField | None = None, reverse_order: bool | None = None, include_permissions: bool | None = None, limit: int | None = None, next: str | None = None) -> Listing[RestCatalog]

listCatalogs → the REST catalogs, draining nextPageToken.

Capped at limit (None = every catalog).

Parameters:

Name	Type	Description	Default
`cloud_environment_id`	`str \| None`	Only the catalogs of this environment; all when left out.	`None`
`filter`	`Sequence[str] \| None`	Conditions such as `name="…"`; only the catalogs that match are kept.	`None`
`sort_by`	`RestCatalogSortField \| None`	The field to sort by: `name`, `createdAt` or `updatedAt`.	`None`
`reverse_order`	`bool \| None`	Sort the other way round.	`None`
`include_permissions`	`bool \| None`	Also say what the caller may do with each one.	`None`
`limit`	`int \| None`	The most catalogs to return; `None` returns every one.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`

Returns:

Type	Description
`Listing[RestCatalog]`	The REST catalogs.

Examples:

>>> found = (
...     datalens.restcatalogs.list(cloud_environment_id="env0000000001").collect().items
... )
>>> [(catalog.id, catalog.name) for catalog in found]
[('cat0000000001', 'lake')]

create ¶

create(*, cloud_environment_id: str, name: str, bucket_settings: RestCatalogBucketSettings, description: str | None = None, labels: Mapping[str, str] | None = None) -> LakehouseOperation

createRestCatalog — make a REST catalog (not measured, never called).

It creates a bucket in a cloud, which may be billed. The reply is an operation: ask lakehouseoperations.get for it until done, then look at its error or its response.

Parameters:

Name	Type	Description	Default
`cloud_environment_id`	`str`	The cloud environment to make it in.	required
`name`	`str`	The catalog's name.	required
`bucket_settings`	`RestCatalogBucketSettings`	The settings of its bucket; an empty one is valid by the document.	required
`description`	`str \| None`	A description.	`None`
`labels`	`Mapping[str, str] \| None`	Labels, a name to a value.	`None`

Returns:

Type	Description
`LakehouseOperation`	The operation that makes it.

Examples:

>>> from ycli.yandex.datalens.restcatalogs.models import RestCatalogBucketSettings
>>> started = datalens.restcatalogs.create(
...     cloud_environment_id="env0000000001",
...     name="lake",
...     bucket_settings=RestCatalogBucketSettings(),
... )
>>> started.id, started.done
('op0000000000006', False)

lakehouseoperations¶

LakehouseOperationsClient ¶

LakehouseOperationsClient(*, session: SyncSession)

Bases: Resource

Lakehouse operations: what making a cloud environment or a REST catalog started.

get ¶

get(operation_id: str) -> LakehouseOperation

getLakehouseOperation → how far an operation is (experimental, not measured).

Ask until done; then error says why it failed, or response holds what it made. An id nothing knows answers 403 Permission denied, not 404.

Parameters:

Name	Type	Description	Default
`operation_id`	`str`	The operation's id.	required

Returns:

Type	Description
`LakehouseOperation`	The operation.

Examples:

>>> state = datalens.lakehouseoperations.get("op0000000000001")
>>> state.done, state.error
(True, None)

trinoclusters¶

TrinoClustersClient ¶

TrinoClustersClient(*, session: SyncSession)

Bases: Resource

Trino clusters: a query engine DataLens runs in a cloud environment, over REST catalogs.

Experimental in the DataLens API. Listing the clusters is measured; the rest is written from the document: a cluster is cloud resources that are billed while it runs, so making, starting, stopping and deleting one, and its catalogs, were never called. An id nothing knows answers 403 Permission denied, not 404.

list ¶

list(*, filter: Sequence[str] | None = None, collection_id: str | None = None, catalog_id: str | None = None, limit: int | None = None, next: str | None = None) -> Listing[TrinoCluster]

listTrinoClusters → the Trino clusters, draining nextPageToken.

Capped at limit (None = every cluster).

Parameters:

Name	Type	Description	Default
`filter`	`Sequence[str] \| None`	Conditions the clusters must meet.	`None`
`collection_id`	`str \| None`	Only the clusters of this collection.	`None`
`catalog_id`	`str \| None`	Only the clusters this REST catalog is attached to.	`None`
`limit`	`int \| None`	The most clusters to return; `None` returns every one.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`

Returns:

Type	Description
`Listing[TrinoCluster]`	The Trino clusters.

Examples:

>>> found = datalens.trinoclusters.list(collection_id="col0000000001").collect().items
>>> [(cluster.id, cluster.status) for cluster in found]
[('tc00000000001', 'RUNNING')]

get ¶

get(id: str) -> TrinoCluster

getTrinoCluster → one Trino cluster (not measured).

Parameters:

Name	Type	Description	Default
`id`	`str`	The cluster's id.	required

Returns:

Type	Description
`TrinoCluster`	The cluster: its configuration, its health, its status and its coordinator.

Examples:

>>> datalens.trinoclusters.get("tc00000000001").name
'reports'

create ¶

create(*, collection_id: str, cloud_environment_id: str, name: str, worker_config: TrinoWorkerConfig, description: str | None = None, labels: Mapping[str, str] | None = None, catalogs_config: Sequence[TrinoNewCatalog] | None = None, trino_version: str | None = None) -> LakehouseOperation

createTrinoCluster — make a Trino cluster (not measured, never called).

A cluster is cloud resources, billed while it runs. The reply is an operation: ask lakehouseoperations.get for it until done.

Parameters:

Name	Type	Description	Default
`collection_id`	`str`	The DataLens collection to make it in.	required
`cloud_environment_id`	`str`	The cloud environment to make it in.	required
`name`	`str`	The cluster's name.	required
`worker_config`	`TrinoWorkerConfig`	The workers: their resource preset and how many there may be.	required
`description`	`str \| None`	A description.	`None`
`labels`	`Mapping[str, str] \| None`	Labels, a name to a value.	`None`
`catalogs_config`	`Sequence[TrinoNewCatalog] \| None`	The REST catalogs to attach.	`None`
`trino_version`	`str \| None`	The version of Trino; the service's own when left out.	`None`

Returns:

Type	Description
`LakehouseOperation`	The operation that makes it.

Examples:

>>> from ycli.yandex.datalens.trinoclusters.models import TrinoWorkerConfig
>>> workers = TrinoWorkerConfig.model_validate(
...     {"resources": {"resourcePresetId": "c4-m16"}}
... )
>>> started = datalens.trinoclusters.create(
...     collection_id="col0000000001",
...     cloud_environment_id="env0000000001",
...     name="reports",
...     worker_config=workers,
... )
>>> started.id
'op0000000000011'

delete ¶

delete(id: str) -> LakehouseOperation

deleteTrinoCluster — delete a Trino cluster (not measured, never called).

Parameters:

Name	Type	Description	Default
`id`	`str`	The cluster's id.	required

Returns:

Type	Description
`LakehouseOperation`	The operation that deletes it.

Examples:

>>> datalens.trinoclusters.delete("tc00000000001").id
'op0000000000012'

start ¶

start(cluster_id: str) -> LakehouseOperation

startTrinoCluster — start a stopped cluster (not measured, never called).

A running cluster is billed.

Parameters:

Name	Type	Description	Default
`cluster_id`	`str`	The cluster's id.	required

Returns:

Type	Description
`LakehouseOperation`	The operation that starts it.

Examples:

>>> datalens.trinoclusters.start("tc00000000001").id
'op0000000000013'

stop ¶

stop(cluster_id: str) -> LakehouseOperation

stopTrinoCluster — stop a running cluster (not measured, never called).

Parameters:

Name	Type	Description	Default
`cluster_id`	`str`	The cluster's id.	required

Returns:

Type	Description
`LakehouseOperation`	The operation that stops it.

Examples:

>>> datalens.trinoclusters.stop("tc00000000001").id
'op0000000000014'

catalog_create ¶

catalog_create(cluster_id: str, *, catalog: TrinoCatalogToAdd) -> LakehouseOperation

addTrinoClusterCatalog — attach a REST catalog (not measured, never called).

Parameters:

Name	Type	Description	Default
`cluster_id`	`str`	The cluster's id.	required
`catalog`	`TrinoCatalogToAdd`	The catalog to attach, by its id.	required

Returns:

Type	Description
`LakehouseOperation`	The operation that attaches it.

Examples:

>>> from ycli.yandex.datalens.trinoclusters.models import TrinoCatalogToAdd
>>> catalog = TrinoCatalogToAdd.model_validate({"catalogId": "cat0000000001"})
>>> datalens.trinoclusters.catalog_create("tc00000000001", catalog=catalog).id
'op0000000000015'

catalog_delete ¶

catalog_delete(cluster_id: str, *, catalog_id: str) -> LakehouseOperation

deleteTrinoClusterCatalog — detach a REST catalog (not measured, never called).

The cluster loses the catalog; the catalog itself stays.

Parameters:

Name	Type	Description	Default
`cluster_id`	`str`	The cluster's id.	required
`catalog_id`	`str`	The id of the catalog to detach.	required

Returns:

Type	Description
`LakehouseOperation`	The operation that detaches it.

Examples:

>>> datalens.trinoclusters.catalog_delete(
...     "tc00000000001", catalog_id="cat0000000001"
... ).id
'op0000000000016'

resource_presets_list ¶

resource_presets_list(cloud_environment_id: str, *, limit: int | None = None, next: str | None = None) -> Listing[TrinoResourcePreset]

listTrinoResourcePresets → the sizes a cluster's machines may have (not measured).

The environment is required: without it the API answers 400.

Parameters:

Name	Type	Description	Default
`cloud_environment_id`	`str`	The cloud environment the presets are of.	required
`limit`	`int \| None`	The most presets to return; `None` returns every one.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`

Returns:

Type	Description
`Listing[TrinoResourcePreset]`	The presets: an id, the cores and the memory of each.

Examples:

>>> presets = (
...     datalens.trinoclusters.resource_presets_list("env0000000001").collect().items
... )
>>> [(preset.id, preset.cores) for preset in presets]
[('c4-m16', '4')]

resource_preset_get ¶

resource_preset_get(resource_preset_id: str, *, cloud_environment_id: str) -> TrinoResourcePreset

getTrinoResourcePreset → one size of a cluster's machines (not measured).

Parameters:

Name	Type	Description	Default
`resource_preset_id`	`str`	The preset's id.	required
`cloud_environment_id`	`str`	The cloud environment the preset is of.	required

Returns:

Type	Description
`TrinoResourcePreset`	The preset: its cores and its memory.

Examples:

>>> datalens.trinoclusters.resource_preset_get(
...     "c4-m16", cloud_environment_id="env0000000001"
... ).memory
'17179869184'

sparkapplications¶

SparkApplicationsClient ¶

SparkApplicationsClient(*, session: SyncSession)

Bases: Resource

Spark applications: the jobs of a Spark cluster, their state and their logs.

Experimental in the DataLens API and written from its document: the owner's instance has no Spark cluster, so no reply was measured. A cluster nothing knows answers 403 Permission denied, not 404.

list ¶

list(cluster_id: str, *, filter: Sequence[str] | None = None, limit: int | None = None, next: str | None = None) -> Listing[SparkApplication]

listSparkApplications → the applications of a cluster (not measured).

Capped at limit (None = every application). The cluster is required: without it the API answers 400.

Parameters:

Name	Type	Description	Default
`cluster_id`	`str`	The Spark cluster's id.	required
`filter`	`Sequence[str] \| None`	Conditions, all of which must hold; each is `field="value"` over `name`, `created_by`, `application_type` or `catalog_id`.	`None`
`limit`	`int \| None`	The most applications to return; `None` returns every one.	`None`
`next`	`str \| None`	What an earlier call returned as `next`. The token carries its listing; give what is required again, and nothing else but the limit.	`None`

Returns:

Type	Description
`Listing[SparkApplication]`	The applications of the cluster.

Examples:

>>> found = datalens.sparkapplications.list("sc00000000001").collect().items
>>> [(application.id, application.status) for application in found]
[('app0000000001', 'RUNNING')]

get ¶

get(cluster_id: str, *, application_id: str) -> SparkApplication

getSparkApplication → one Spark application (not measured).

Parameters:

Name	Type	Description	Default
`cluster_id`	`str`	The Spark cluster's id.	required
`application_id`	`str`	The application's id.	required

Returns:

Type	Description
`SparkApplication`	The application: its status, its times and what it runs.

Examples:

>>> datalens.sparkapplications.get("sc00000000001", application_id="app0000000001").name
'nightly'

create ¶

create(body: SparkApplicationCreate) -> LakehouseOperation

createSparkApplication — make a Spark application (not measured, never called).

The request is one of three kinds, told apart by the field that holds the application: sparkApplication (a JAR), pysparkApplication (a Python file) or sparkConnectApplication.

Parameters:

Name	Type	Description	Default
`body`	`SparkApplicationCreate`	The application to make: the cluster, a name, the catalogs to attach and exactly one of the three kinds.	required

Returns:

Type	Description
`LakehouseOperation`	The operation that makes it.

Examples:

>>> from ycli.yandex.datalens.sparkapplications.models import SparkApplicationCreate
>>> new = SparkApplicationCreate.model_validate(
...     {
...         "clusterId": "sc00000000001",
...         "name": "nightly",
...         "pysparkApplication": {"mainPythonFileUri": "s3a://bucket/jobs/nightly.py"},
...     }
... )
>>> datalens.sparkapplications.create(new).id
'op0000000000022'

cancel ¶

cancel(cluster_id: str, *, application_id: str) -> LakehouseOperation

cancelSparkApplication — stop a Spark application (not measured, never called).

Parameters:

Name	Type	Description	Default
`cluster_id`	`str`	The Spark cluster's id.	required
`application_id`	`str`	The application's id.	required

Returns:

Type	Description
`LakehouseOperation`	The operation that cancels it.

Examples:

>>> datalens.sparkapplications.cancel(
...     "sc00000000001", application_id="app0000000001"
... ).id
'op0000000000021'

log_list ¶

log_list(cluster_id: str, *, application_id: str, page_size: int | None = None, page_token: str | None = None) -> SparkApplicationLog

listSparkApplicationLog → one fragment of an application's log (not measured).

Give next_page_token of a fragment back as page_token for the next one.

Parameters:

Name	Type	Description	Default
`cluster_id`	`str`	The Spark cluster's id.	required
`application_id`	`str`	The application's id.	required
`page_size`	`int \| None`	The most characters the fragment may hold.	`None`
`page_token`	`str \| None`	The token of the fragment to read; the first when left out.	`None`

Returns:

Type	Description
`SparkApplicationLog`	The fragment and the token of the next one.

Examples:

>>> fragment = datalens.sparkapplications.log_list(
...     "sc00000000001", application_id="app0000000001"
... )
>>> fragment.content, fragment.next_page_token
('driver started', 'l2')