Cluster · разработчикам
app.db
Короткие запросы к данным и фабрики разделов, записей и транзакционных пакетов.
Все методы SDK · Типы и ошибки
Получение объекта
scope = app.db.scope("notes/")__init__
Создаёт Database. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.
def __init__(app: App) -> None: ...Аргументы
app: App, обязательный. Переданный ядром объект app. Второй App в модуле создавать не нужно.
Результат
None. Создаёт Database. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
- Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.
Пример
# Обычный способ получения объекта:
scope = app.db.scope("notes/")__call__
Создаёт раздел с префиксом. Сокращение для scope().
def __call__(prefix: str = '', **target: JSON) -> Scope: ...Аргументы
prefix: str, по умолчанию''. Префикс ключей, добавляется без автоматического разделителя.target: JSON, произвольные именованные аргументы. Допустимые именованные параметры: module, slot. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.
Результат
Scope. Создаёт раздел с префиксом. Сокращение для scope().
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
- Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.
Пример
result = app.db(module=None, slot=None)scope
Выбирает префикс ключей и необязательный раздел другого экземпляра своего юзербота.
def scope(prefix: str = '', module: str | None = None, slot: str | None = None) -> Scope: ...Аргументы
prefix: str, по умолчанию''. Префикс ключей, добавляется без автоматического разделителя.module: str | None, по умолчаниюNone. ID публикации модуля. None выбирает текущий раздел там, где это предусмотрено.slot: str | None, по умолчаниюNone. Имя профиля экземпляра. None использует выбор зависимости или текущий профиль.
Результат
Scope. Выбирает префикс ключей и необязательный раздел другого экземпляра своего юзербота.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
- Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.
Пример
result = app.db.scope()record
Создаёт объект записи текущего экземпляра; default используется, если ключ отсутствует.
def record(key: str, default: JSON = None) -> Record: ...Аргументы
key: str, обязательный. Непустой ключ записи либо постоянный ключ кнопки в указанном объекте.default: JSON, по умолчаниюNone. Возвращаемое или исходное значение при отсутствии данных. Объекты JSON копируются.
Результат
Record. Создаёт объект записи текущего экземпляра; default используется, если ключ отсутствует.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
- Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.
Пример
result = app.db.record("count")batch
Создаёт атомарный пакет изменений текущего раздела. До commit() база не меняется.
def batch() -> Batch: ...Аргументы
Нет.
Результат
Batch. Создаёт атомарный пакет изменений текущего раздела. До commit() база не меняется.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
- Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.
Пример
result = app.db.batch()items
Перебирает пары ключ и значение текущего раздела. Между порциями данные могут меняться; это не единый снимок.
def items(limit: int = 100) -> AsyncIterator[tuple[str, JSON]]: ...Аргументы
limit: int, по умолчанию100. Размер порции. Для db.keys: 1..1000; файлов и договоров: 1..100. get_messages: смотри ограничения Telegram-клиента.
Результат
AsyncIterator[tuple[str, JSON]]. Перебирает пары ключ и значение текущего раздела. Между порциями данные могут меняться; это не единый снимок.
Права
Нужны db.read. Для другого раздела своего юзербота дополнительно db.full.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = app.db.items()get
Возвращает сохранённое значение либо default для отсутствующего или истёкшего ключа.
async def get(key: str, default: JSON = None, **kwargs: JSON) -> JSON: ...Аргументы
key: str, обязательный. Непустой ключ записи либо постоянный ключ кнопки в указанном объекте.default: JSON, по умолчаниюNone. Возвращаемое или исходное значение при отсутствии данных. Объекты JSON копируются.kwargs: JSON, произвольные именованные аргументы. Допустимые именованные параметры: module, slot. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.
Результат
JSON. Возвращает сохранённое значение либо default для отсутствующего или истёкшего ключа.
Права
Нужны db.read. Для другого раздела своего юзербота дополнительно db.full.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = await app.db.get("count", module=None, slot=None)set
Записывает значение ключа с необязательным сроком хранения. Возвращает True при успехе.
async def set(key: str, value: JSON, **kwargs: JSON) -> bool: ...Аргументы
key: str, обязательный. Непустой ключ записи либо постоянный ключ кнопки в указанном объекте.value: JSON, обязательный. JSON-значение: только поддерживаемые типы; NaN, бесконечность и произвольные объекты запрещены.kwargs: JSON, произвольные именованные аргументы. Допустимые именованные параметры: ttl, module, slot. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.
Результат
bool. Записывает значение ключа с необязательным сроком хранения. Возвращает True при успехе.
Права
Нужны db.write. Для другого раздела своего юзербота дополнительно db.full.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = await app.db.set("count", {"count": 1}, ttl=3600)delete
Удаляет ключ. Возвращает, существовал ли он на момент удаления.
async def delete(key: str, **kwargs: JSON) -> bool: ...Аргументы
key: str, обязательный. Непустой ключ записи либо постоянный ключ кнопки в указанном объекте.kwargs: JSON, произвольные именованные аргументы. Допустимые именованные параметры: module, slot. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.
Результат
bool. Удаляет ключ. Возвращает, существовал ли он на момент удаления.
Права
Нужны db.write. Для другого раздела своего юзербота дополнительно db.full.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = await app.db.delete("count", module=None, slot=None)keys
Возвращает порцию имён ключей и курсор after. Передавай курсор без изменений до получения None.
async def keys(**kwargs: JSON) -> KeysPage: ...Аргументы
kwargs: JSON, произвольные именованные аргументы. Допустимые именованные параметры: module, slot, after, limit. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.
Результат
KeysPage. Возвращает порцию имён ключей и курсор after. Передавай курсор без изменений до получения None.
Права
Нужны db.read. Для другого раздела своего юзербота дополнительно db.full.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = await app.db.keys(limit=20)