diff options
| author | alexv-smirnov <alexv-smirnov@yandex-team.ru> | 2022-02-22 22:50:39 +0300 |
|---|---|---|
| committer | alexv-smirnov <alexv-smirnov@yandex-team.ru> | 2022-02-22 22:50:39 +0300 |
| commit | 31b86286f54e3940d5f130127a8745bfef3f2a38 (patch) | |
| tree | d5d6708b44616ff5c1ea4f5778741581b8de1d01 | |
| parent | 6cc6ec41e99dad8aed2947030be6c06cc8c5ad85 (diff) | |
| download | ydb-31b86286f54e3940d5f130127a8745bfef3f2a38.tar.gz | |
PR from branch users/alexv-smirnov/feature/YCDOCS-4091-ydb-docs-oss-c5
ydb docs sdk refactored
ydb docs operations-index bug fixed by file renaming
ydb docs sdk python/go download/run secions
ref:1f06bab4af63a2914a457b00111c08f57b29b54f
53 files changed, 657 insertions, 192 deletions
diff --git a/ydb/docs/presets.yaml b/ydb/docs/presets.yaml index 393e4c8c616..34487033135 100644 --- a/ydb/docs/presets.yaml +++ b/ydb/docs/presets.yaml @@ -27,3 +27,4 @@ default: ydb-cli: ydb k8s: Kubernetes + oss: true diff --git a/ydb/docs/ru/core/getting_started/_includes/auth.md b/ydb/docs/ru/core/getting_started/_includes/auth.md index dc664efd9da..1fa3f327f33 100644 --- a/ydb/docs/ru/core/getting_started/_includes/auth.md +++ b/ydb/docs/ru/core/getting_started/_includes/auth.md @@ -4,4 +4,4 @@ Быстрые рецепты настройки аутентификации при соединении с БД в облачных сервисах или в корпоративных контекстах описаны в их документации в разделе YDB / Начало работы / Аутентификация. -Полная информация о всех доступных способах аутентификации приведена в статье [Соединение в БД](../../concepts/connect.md) в разделе "Концепции". +Полная информация о всех доступных способах аутентификации приведена в статье [Соединение с базой данных](../../concepts/connect.md) в разделе "Концепции". diff --git a/ydb/docs/ru/core/getting_started/_includes/auth_sdk_overlay.md b/ydb/docs/ru/core/getting_started/_includes/auth_sdk_overlay.md new file mode 100644 index 00000000000..e69de29bb2d --- /dev/null +++ b/ydb/docs/ru/core/getting_started/_includes/auth_sdk_overlay.md diff --git a/ydb/docs/ru/core/getting_started/_includes/sdk.md b/ydb/docs/ru/core/getting_started/_includes/sdk.md index 0108639a4c6..86148bd03c9 100644 --- a/ydb/docs/ru/core/getting_started/_includes/sdk.md +++ b/ydb/docs/ru/core/getting_started/_includes/sdk.md @@ -1,5 +1,16 @@ # YDB SDK - Начало работы -YDB SDK - набор программных компонентов на разных языках программирования, поддерживающих работу с базами данных YDB. +YDB SDK - набор программных компонентов, поддерживающих работу с базами данных YDB для приложений на разных языках программирования. + +Выполните следующие шаги для запуска простейшего приложения, использующего YDB: + +1. [Установите YDB SDK](../../reference/ydb-sdk/install.md) для нужного языка программирования + +2. Скачайте и запустите готовое тестовое приложение, использующее SDK для установленного языка программирования, и изучите его код: + + - [Python](../../reference/ydb-sdk/example/python/index.md) + - [Go](../../reference/ydb-sdk/example/go/index.md) + +Полная информация о YDB SDK находится в разделе [Работа с YDB SDK](../../reference/ydb-sdk/index.md). + -Перейдите в раздел [справочника по YDB SDK](../../reference/ydb-sdk/index.md), чтобы продолжить занкомство.
\ No newline at end of file diff --git a/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md b/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md index 83685314c86..e0d65dba4ff 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md +++ b/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md @@ -54,10 +54,10 @@ scripting yql | Выполнение YQL-скрипта table attribute add | Добавление атрибута таблицы table attribute drop | Удаление атрибута таблицы table drop | Удаление таблицы -[table index add global](../commands/operations-index.md) | Добавление синхронного индекса -[table index add global-async](../commands/operations-index.md) | Добавление асинхронного индекса -[table index add global-sync](../commands/operations-index.md) | Добавление синхронного индекса -[table index drop](../commands/operations-index.md) | Удаление индекса +[table index add global](../commands/index-ops.md) | Добавление синхронного индекса +[table index add global-async](../commands/index-ops.md) | Добавление асинхронного индекса +[table index add global-sync](../commands/index-ops.md) | Добавление синхронного индекса +[table index drop](../commands/index-ops.md) | Удаление индекса [table query execute](../commands/query.md) | Исполнение YQL-запроса [table query explain](../commands/explain-plan.md) | План исполнения YQL-запроса [table readtable](../commands/readtable.md) | Потоковое чтение таблицы diff --git a/ydb/docs/ru/core/reference/ydb-cli/_includes/connect.md b/ydb/docs/ru/core/reference/ydb-cli/_includes/connect.md index a7920bfb704..85393c72aa5 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/_includes/connect.md +++ b/ydb/docs/ru/core/reference/ydb-cli/_includes/connect.md @@ -1,4 +1,4 @@ -# Соединение CLI с базой данных и аутентификация {#start} +# Соединение CLI с базой данных и аутентификация Большинство команд YDB CLI относятся к операциям над базой данных YDB, и требуют соединения с ней для исполнения. diff --git a/ydb/docs/ru/core/reference/ydb-cli/_includes/index.md b/ydb/docs/ru/core/reference/ydb-cli/_includes/index.md index cc47c57fd43..fc22adb2f55 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/_includes/index.md +++ b/ydb/docs/ru/core/reference/ydb-cli/_includes/index.md @@ -1,6 +1,6 @@ # {{ ydb-short-name }} CLI -Интерфейс командной строки {{ ydb-short-name }} CLI — скачиваемое программное обеспечение для управления вашими данными в YDB. +Интерфейс командной строки {{ ydb-short-name }} CLI — программа для управления вашими данными в YDB. Для того чтобы воспользоваться {{ ydb-short-name }} CLI, ознакомьтесь со статьей [Установка YDB CLI](../install.md). @@ -15,6 +15,6 @@ * [Работа с директориями](../commands/dir.md). * [Выполнение запроса к данным](../commands/query.md). * [Потоковое чтение таблицы](../commands/readtable.md). -* [Работа со вторичными индексами](../commands/operations-index.md). +* [Работа со вторичными индексами](../commands/index-ops.md). * [Получение списка эндпоинтов для базы данных](../commands/discovery-list.md). * [Нагрузочное тестирование](../commands/workload/index.md). diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/operations-index.md b/ydb/docs/ru/core/reference/ydb-cli/commands/index-ops.md index 8905766ce62..8905766ce62 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/commands/operations-index.md +++ b/ydb/docs/ru/core/reference/ydb-cli/commands/index-ops.md diff --git a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml index 12383f1df59..5e86552ee8a 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml +++ b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml @@ -28,7 +28,7 @@ items: - name: Потоковое чтение таблицы href: commands/readtable.md - name: Работа со вторичными индексами - href: commands/operations-index.md + href: commands/index-ops.md - name: Скан запросы href: commands/scan-query.md # - name: Утилиты diff --git a/ydb/docs/ru/core/reference/ydb-sdk/_includes/auth.md b/ydb/docs/ru/core/reference/ydb-sdk/_includes/auth.md index 652d2c39718..27ad1a08e56 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/_includes/auth.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/_includes/auth.md @@ -2,12 +2,12 @@ Как описано в статье о [подключении клиента YDB к серверу и аутентификации](../../../concepts/connect.md), для успешной аутентификации в запрос клиентом должен быть добавлен аутентификационный токен, проверяемый сервером. -Драйвер YDB в SDK использует объект, отвечающий за генерацию таких токенов. SDK предоставляет встроенные методы получения такого объекта: +YDB SDK использует объект, отвечающий за генерацию таких токенов. SDK предоставляет встроенные методы получения такого объекта: 1. Специализированные методы под разные [режимы аутентификации](../../../concepts/connect.md#auth-modes) с явной передачей параметров. 2. Метод определения режима аутентификации и необходимых параметров из окружения, в котором запускается приложение. -Обычно объект генерации токенов создается перед инициализацией драйвера, и передается параметром в его конструктор. C++ и Go SDK дополнительно позволяют через один драйвер работать с несколькими БД и объектами генерации токенов. +Обычно объект генерации токенов создается перед инициализацией драйвера YDB, и передается параметром в его конструктор. C++ и Go SDK дополнительно позволяют через один драйвер работать с несколькими БД и объектами генерации токенов. Если объект генерации токенов не определен, драйвер не будет добавлять в запросы какой-либо аутентификационной информации, что может позволить успешно соединиться с локально развернутыми кластерами YDB, не требующими аутентификации. Для всех доступных по сети баз данных такие запросы будут отклонены с выдачей ошибки аутентификации. @@ -19,43 +19,43 @@ - Python - Режим | Метод + [Режим](../../../concepts/connect.md#auth-modes) | Метод ----- | ----- Anonymous | [`ydb.AnonymousCredentials()`](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/anonymous-credentials) Access Token | [`ydb.AccessTokenCredentials( token )`](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/access-token-credentials) Metadata | [`ydb.iam.MetadataUrlCredentials()`](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/metadata-credentials) Service Account Key | [`ydb.iam.ServiceAccountCredentials.from_file(`</br> `key_file, iam_endpoint=None, iam_channel_credentials=None )`](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/service-account-credentials) - Из окружения | `ydb.construct_credentials_from_environ()` + Определяется по переменным окружения | `ydb.construct_credentials_from_environ()` - Go - Режим | Пакет | Метод + [Режим](../../../concepts/connect.md#auth-modes) | Пакет | Метод ----- | ----- | ---- Anonymous | [ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk/blob/master/go.mod) | [`ydb.WithAnonymousCredentials()`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/anonymous_credentials) Access Token | [ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk/blob/master/go.mod) | [`ydb.WithAccessTokenCredentials( token )`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/access_token_credentials) Metadata | [ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc/blob/master/go.mod) | [`yc.WithMetadataCredentials( ctx )`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/metadata_credentials) Service Account Key | [ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc/blob/master/go.mod) | [`yc.WithServiceAccountKeyFileCredentials( key_file )`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/service_account_credentials) - Из окружения | [ydb-go-sdk-auth-environ](https://github.com/ydb-platform/ydb-go-sdk-auth-environ/blob/master/go.mod) | [`environ.WithEnvironCredentials(ctx)`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/environ) + Определяется по переменным окружения | [ydb-go-sdk-auth-environ](https://github.com/ydb-platform/ydb-go-sdk-auth-environ/blob/master/go.mod) | [`environ.WithEnvironCredentials(ctx)`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/environ) - Java - Режим | Метод + [Режим](../../../concepts/connect.md#auth-modes) | Метод ----- | ----- Anonymous | [`com.yandex.ydb.core.auth.NopAuthProvider.INSTANCE`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/anonymous_credentials) Access Token | [`com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(`</br> `yandex.cloud.sdk.auth.provider.IamTokenCredentialProvider`</br> `.builder()`</br> `.token(accessToken)`</br> `.build()`</br>`);`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/access_token_credentials) Metadata | [`com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(`</br> `yandex.cloud.sdk.auth.provider.ComputeEngineCredentialProvider`</br> `.builder()`</br> `.build()`</br>`);`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/metadata_credentials) Service Account Key | [`com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(`</br> `yandex.cloud.sdk.auth.provider.ApiKeyCredentialProvider`</br> `.builder()`</br> `.fromFile(Paths.get(saKeyFile))`</br> `.build()`</br>`);`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/service_account_credentials) - Из окружения | [`com.yandex.ydb.auth.iam.CloudAuthHelper.getAuthProviderFromEnviron();`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/environ/src/main/java/com/yandex/ydb/example) + Определяется по переменным окружения | [`com.yandex.ydb.auth.iam.CloudAuthHelper.getAuthProviderFromEnviron();`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/environ/src/main/java/com/yandex/ydb/example) - Node.js - Режим | Метод + [Режим](../../../concepts/connect.md#auth-modes) | Метод ----- | ----- Anonymous | [`new 'ydb-sdk'.AnonymousAuthService()`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/anonymous-credentials) Access Token | [`new 'ydb-sdk'.TokenAuthService( accessToken, database )`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/access-token-credentials) Metadata | [`new 'ydb-sdk'.MetadataAuthService( database )`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/metadata-credentials) Service Account Key | [`new 'ydb-sdk'.getSACredentialsFromJson( saKeyFile )`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/service-account-credentials) - Из окружения | [`new 'ydb-sdk'.getCredentialsFromEnv( entryPoint, database, logger )`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/environ) + Определяется по переменным окружения | [`new 'ydb-sdk'.getCredentialsFromEnv( entryPoint, database, logger )`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/environ) {% endlist %} diff --git a/ydb/docs/ru/core/reference/ydb-sdk/_includes/index/intro.md b/ydb/docs/ru/core/reference/ydb-sdk/_includes/index.md index 50df097a51d..e7fd1a316bf 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/_includes/index/intro.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/_includes/index.md @@ -1,12 +1,23 @@ # YDB SDK +{% include [index_intro_overlay.md](index_intro_overlay.md) %} + Для работы с YDB доступны OpenSource SDK для следующих языков программирования: -{% if cpp_oss_link %} -- C++ [{{ cpp_oss_link }}]({{ cpp_oss_link }}){% endif %} -- Python [https://github.com/yandex-cloud/ydb-python-sdk](https://github.com/yandex-cloud/ydb-python-sdk) +{% if oss %} +- C++ [https://github.com/ydb-platform/ydb/tree/main/ydb/public/sdk/cpp](https://github.com/ydb-platform/ydb/tree/main/ydb/public/sdk/cpp) +{% endif %} +- С# (.NET) [https://github.com/ydb-platform/ydb-dotnet-sdk](https://github.com/ydb-platform/ydb-dotnet-sdk) - Go [https://github.com/ydb-platform/ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk) (архивные версии [v1](https://github.com/yandex-cloud/ydb-go-sdk/tree/v1.5.1) и [v2](https://github.com/yandex-cloud/ydb-go-sdk/tree/v2.11.2)) +- Java [https://github.com/yandex-cloud/ydb-java-sdk](https://github.com/yandex-cloud/ydb-java-sdk) - Node.js [https://github.com/yandex-cloud/ydb-nodejs-sdk](https://github.com/yandex-cloud/ydb-nodejs-sdk) - PHP [https://github.com/yandex-cloud/ydb-php-sdk](https://github.com/yandex-cloud/ydb-php-sdk) -- Java [https://github.com/yandex-cloud/ydb-java-sdk](https://github.com/yandex-cloud/ydb-java-sdk) -- С# (.NET) [https://github.com/ydb-platform/ydb-dotnet-sdk](https://github.com/ydb-platform/ydb-dotnet-sdk) +- Python [https://github.com/yandex-cloud/ydb-python-sdk](https://github.com/yandex-cloud/ydb-python-sdk) + +Документация по SDK содержит следующие разделы: + +- [Установка](../install.md) +- [Аутентификация](../auth.md) +- [Тестовое приложение](../example/index.md) +- [Рецепты кода](../recipes/index.md) + diff --git a/ydb/docs/ru/core/reference/ydb-sdk/_includes/index/examples.md b/ydb/docs/ru/core/reference/ydb-sdk/_includes/index/examples.md deleted file mode 100644 index 15022ca5f5d..00000000000 --- a/ydb/docs/ru/core/reference/ydb-sdk/_includes/index/examples.md +++ /dev/null @@ -1 +0,0 @@ -В разделе [Тестовое приложение](../../example/index.md) разбирается код тестового приложения, реализованного с применением YDB SDK для разных языков программирования. diff --git a/ydb/docs/ru/core/reference/ydb-sdk/_includes/index_intro_overlay.md b/ydb/docs/ru/core/reference/ydb-sdk/_includes/index_intro_overlay.md new file mode 100644 index 00000000000..e69de29bb2d --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/_includes/index_intro_overlay.md diff --git a/ydb/docs/ru/core/reference/ydb-sdk/_includes/install.md b/ydb/docs/ru/core/reference/ydb-sdk/_includes/install.md new file mode 100644 index 00000000000..3b3a2a3d334 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/_includes/install.md @@ -0,0 +1,37 @@ +# Установка SDK + +Ниже приведены инструкции по быстрой установке OpenSource SDK. На рабочей станции должны быть предварительно установлены и сконфигурированы инструменты по работе с выбранным языком программирования, а также пакетные менеджеры. + +Описание порядка сборки из исходного кода размещено в репозиториях исходного кода на github.com, ссылки на которые приведены на странице [YDB SDK - Обзор](../index.md). + +{% list tabs %} + +- Python + + Выполните команду из командной строки: + + {% include [install/cmd_python.md](install/cmd_python.md) %} + + Если команда не выполнилась успешно, убедитесь, что в вашем окружении установлен [Python3](https://www.python.org/downloads/) версии 3.8 или более новой, со включенным пакетным менеджером [pip](https://pypi.org/project/pip/). + +- Go + + Выполните команду из командной строки: + + {% include [install/cmd_go.md](install/cmd_go.md) %} + + Для успешной установки в вашем окружении должен быть установлен [Go](https://go.dev/doc/install) версии не ниже 1.13. + +- С# (.NET) + + {% include [install/cmd_dotnet.md](install/cmd_dotnet.md) %} + +- Java + + Добавьте зависимости в Maven-проект как описано в пункте ["Install the SDK"](https://github.com/yandex-cloud/ydb-java-sdk#install-the-sdk) файла `readme.md` в репозитории исходного кода. + +- PHP + + {% include [install/cmd_php.md](install/cmd_php.md) %} + +{% endlist %}
\ No newline at end of file diff --git a/ydb/docs/ru/core/reference/ydb-sdk/_includes/install/cmd_dotnet.md b/ydb/docs/ru/core/reference/ydb-sdk/_includes/install/cmd_dotnet.md new file mode 100644 index 00000000000..01f626af6b1 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/_includes/install/cmd_dotnet.md @@ -0,0 +1,3 @@ +``` bash +dotnet add package Ydb.Sdk +``` diff --git a/ydb/docs/ru/core/reference/ydb-sdk/_includes/install/cmd_go.md b/ydb/docs/ru/core/reference/ydb-sdk/_includes/install/cmd_go.md new file mode 100644 index 00000000000..b3a4cb88127 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/_includes/install/cmd_go.md @@ -0,0 +1,3 @@ +``` bash +go get -u github.com/ydb-platform/ydb-go-sdk/v3 +``` diff --git a/ydb/docs/ru/core/reference/ydb-sdk/_includes/install/cmd_php.md b/ydb/docs/ru/core/reference/ydb-sdk/_includes/install/cmd_php.md new file mode 100644 index 00000000000..ea964a35dbe --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/_includes/install/cmd_php.md @@ -0,0 +1,3 @@ +``` bash +composer require yandex-cloud/ydb-php-sdk +``` diff --git a/ydb/docs/ru/core/reference/ydb-sdk/_includes/install/cmd_python.md b/ydb/docs/ru/core/reference/ydb-sdk/_includes/install/cmd_python.md new file mode 100644 index 00000000000..f0b6edf2eab --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/_includes/install/cmd_python.md @@ -0,0 +1,3 @@ +``` bash +python3 -m pip install ydb +```
\ No newline at end of file diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-cpp.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-cpp.md index 78ad3a46a78..0ac9b5d0d8e 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-cpp.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-cpp.md @@ -1,6 +1,6 @@ # Приложение на C++ -На этой странице подробно разбирается код [тестового приложения](https://a.yandex-team.ru/arc/trunk/arcadia/ydb/public/sdk/cpp/examples/basic_example), доступного в составе [C++ SDK](https://a.yandex-team.ru/arc/trunk/arcadia/ydb/public/sdk/cpp) {{ ydb-short-name }}. +На этой странице подробно разбирается код [тестового приложения](https://github.com/ydb-platform/ydb/tree/main/ydb/public/sdk/cpp/examples/basic_example), доступного в составе [C++ SDK](https://github.com/ydb-platform/ydb/tree/main/ydb/public/sdk/cpp) {{ ydb-short-name }}. {% include [init.md](steps/01_init.md) %} @@ -21,7 +21,7 @@ TClient client(driver); ``` -{% include [create_table.md](steps/02_create_table.md) %} +{% include [steps/02_create_table.md](steps/02_create_table.md) %} Для создания таблиц используется метод `CreateTable`: @@ -71,9 +71,28 @@ Column, name: series_info, type: Utf8? Column, name: release_date, type: Uint64? ``` +{% include [steps/03_write_queries.md](steps/03_write_queries.md) %} + +Фрагмент кода, демонстрирующий выполнение запроса на запись/изменение данных: + +```c++ +//! Shows basic usage of mutating operations. +static TStatus UpsertSimpleTransaction(TSession session, const TString& path) { + auto query = Sprintf(R"( + PRAGMA TablePathPrefix("%s"); + + UPSERT INTO episodes (series_id, season_id, episode_id, title) VALUES + (2, 6, 1, "TBD"); + )", path.c_str()); + + return session.ExecuteDataQuery(query, + TTxControl::BeginTx(TTxSettings::SerializableRW()).CommitTx()).GetValueSync(); +} +``` + {% include [pragmatablepathprefix.md](auxilary/pragmatablepathprefix.md) %} -{% include [query_processing.md](steps/03_query_processing.md) %} +{% include [steps/04_query_processing.md](steps/04_query_processing.md) %} Для выполнения YQL-запросов используется метод `ExecuteDataQuery`. SDK позволяет в явном виде контролировать выполнение транзакций и настраивать необходимый режим выполнения транзакций с помощью класса `TTxControl`. @@ -111,7 +130,7 @@ static TStatus SelectSimpleTransaction(TSession session, const TString& path, } ``` -{% include [results_processing.md](steps/04_results_processing.md) %} +{% include [steps/05_results_processing.md](steps/05_results_processing.md) %} Для обработки результатов выполнения запроса используется класс `TResultSetParser`. Фрагмент кода, приведенный ниже, демонстрирует обработку результатов запроса с помощью объекта `parser`: @@ -134,24 +153,7 @@ static TStatus SelectSimpleTransaction(TSession session, const TString& path, series, Id: 1, title: IT Crowd, Release date: 2006-02-03 ``` -{% include [write_queries.md](steps/05_write_queries.md) %} - -Фрагмент кода, демонстрирующий выполнение запроса на запись/изменение данных: - -```c++ -//! Shows basic usage of mutating operations. -static TStatus UpsertSimpleTransaction(TSession session, const TString& path) { - auto query = Sprintf(R"( - PRAGMA TablePathPrefix("%s"); - UPSERT INTO episodes (series_id, season_id, episode_id, title) VALUES - (2, 6, 1, "TBD"); - )", path.c_str()); - - return session.ExecuteDataQuery(query, - TTxControl::BeginTx(TTxSettings::SerializableRW()).CommitTx()).GetValueSync(); -} -``` {% include [param_queries.md](steps/06_param_queries.md) %} @@ -429,4 +431,3 @@ static TStatus ExplicitTclTransaction(TSession session, const TString& path, con } ``` -{% include [error_handling.md](steps/50_error_handling.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-dotnet.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-dotnet.md index e1b040581d5..5f4e89edbaa 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-dotnet.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-dotnet.md @@ -1,10 +1,10 @@ # Приложение на C# (.NET) -На этой странице подробно разбирается код [тестового приложения](https://github.com/ydb-platform/ydb-dotnet-examples), доступного в составе [C# (.NET) SDK](https://github.com/ydb-platform/ydb-dotnet-sdk) {{ ydb-short-name }}. +На этой странице подробно разбирается код [тестового приложения](https://github.com/ydb-platform/ydb-dotnet-examples), использующего [C# (.NET) SDK](https://github.com/ydb-platform/ydb-dotnet-sdk) {{ ydb-short-name }}. {% include [addition.md](auxilary/addition.md) %} -{% include [init.md](steps/01_init.md) %} +{% include [steps/01_init.md](steps/01_init.md) %} Фрагмент кода приложения для инициализации драйвера: @@ -34,7 +34,7 @@ public static async Task Run( using var tableClient = new TableClient(driver, new TableClientConfig()); ``` -{% include [create_table.md](steps/02_create_table.md) %} +{% include [steps/02_create_table.md](steps/02_create_table.md) %} Для создания таблиц используется метод `session.ExecuteSchemeQuery` с DDL (Data Definition Language) YQL-запросом. @@ -73,9 +73,40 @@ var response = await tableClient.SessionExec(async session => response.Status.EnsureSuccess(); ``` +{% include [steps/03_write_queries.md](steps/03_write_queries.md) %} + +Фрагмент кода, демонстрирующий выполнение запроса на запись/изменение данных: + +```c# +var response = await tableClient.SessionExec(async session => +{ + var query = @" + DECLARE $id AS Uint64; + DECLARE $title AS Utf8; + DECLARE $release_date AS Date; + + UPSERT INTO series (series_id, title, release_date) VALUES + ($id, $title, $release_date); + "; + + return await session.ExecuteDataQuery( + query: query, + txControl: TxControl.BeginSerializableRW().Commit(), + parameters: new Dictionary<string, YdbValue> + { + { "$id", YdbValue.MakeUint64(1) }, + { "$title", YdbValue.MakeUtf8("NewTitle") }, + { "$release_date", YdbValue.MakeDate(DateTime.UtcNow) } + } + ); +}); + +response.Status.EnsureSuccess(); +``` + {% include [pragmatablepathprefix.md](auxilary/pragmatablepathprefix.md) %} -{% include [query_processing.md](steps/03_query_processing.md) %} +{% include [steps/04_query_processing.md](steps/04_query_processing.md) %} Для выполнения YQL-запросов используется метод `session.ExecuteDataQuery()`. SDK позволяет в явном виде контролировать выполнение транзакций и настраивать необходимый режим выполнения транзакций с помощью класса `TxControl`. В фрагменте кода, приведенном ниже, используется транзакция с режимом `SerializableRW` и автоматическим коммитом после выполнения запроса. Значения параметров запроса передаются в виде словаря имя-значение в аргументе `parameters`. @@ -108,7 +139,7 @@ var queryResponse = (ExecuteDataQueryResponse)response; var resultSet = queryResponse.Result.ResultSets[0]; ``` -{% include [results_processing.md](steps/04_results_processing.md) %} +{% include [steps/05_results_processing.md](steps/05_results_processing.md) %} Результат выполнения запроса (ResultSet) состоит из упорядоченного набора строк (Rows). Пример обработки результата выполнения запроса: @@ -122,36 +153,7 @@ foreach (var row in resultSet.Rows) } ``` -{% include [write_queries.md](steps/05_write_queries.md) %} -Фрагмент кода, демонстрирующий выполнение запроса на запись/изменение данных: - -```c# -var response = await tableClient.SessionExec(async session => -{ - var query = @" - DECLARE $id AS Uint64; - DECLARE $title AS Utf8; - DECLARE $release_date AS Date; - - UPSERT INTO series (series_id, title, release_date) VALUES - ($id, $title, $release_date); - "; - - return await session.ExecuteDataQuery( - query: query, - txControl: TxControl.BeginSerializableRW().Commit(), - parameters: new Dictionary<string, YdbValue> - { - { "$id", YdbValue.MakeUint64(1) }, - { "$title", YdbValue.MakeUtf8("NewTitle") }, - { "$release_date", YdbValue.MakeDate(DateTime.UtcNow) } - } - ); -}); - -response.Status.EnsureSuccess(); -``` {% include [scan_query.md](steps/08_scan_query.md) %} @@ -183,5 +185,3 @@ public void executeScanQuery() } } ``` - -{% include [error_handling.md](steps/50_error_handling.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-go.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-go.md index d5dc6484f4b..2235b3c697f 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-go.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-go.md @@ -1,3 +1,4 @@ +<<<<<<< ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-go.md # Приложение на Go На этой странице подробно разбирается код [тестового приложения](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/basic), использующего [Go SDK](https://github.com/ydb-platform/ydb-go-sdk/v3) {{ ydb-short-name }}. @@ -59,7 +60,7 @@ defer func() { Наиболее востребован метод `db.Table().Do(ctx, op)`, который реализует фоновое создание сессий и повторные попытки выполнить пользовательскую операцию `op`, в которую пользовательскому коду отдается подготовленная сессия. Сессия имеет исчерпывающее `API`, позволяющее выполнять `DDL`, `DML`, `DQL` и `TCL` запросы. -## Создание таблиц с помощью CreateTable API {#create-table-api} +{% include [steps/02_create_table.md](steps/02_create_table.md) %} Для создания таблиц используется метод `table.Session.CreateTable()`: @@ -104,7 +105,7 @@ if err != nil { } ``` -## Обработка запросов и транзакций {#query-processing} +{% include [steps/04_query_processing.md](steps/04_query_processing.md) %} Для выполнения YQL-запросов используется метод `table.Session.Execute()`. SDK позволяет в явном виде контролировать выполнение транзакций и настраивать необходимый режим выполнения транзакций с помощью структуры `table.TxControl`. @@ -248,7 +249,6 @@ if err != nil { } ``` -{% include [error_handling.md](steps/50_error_handling.md) %} {% note info %} @@ -257,3 +257,5 @@ if err != nil { - [github.com/yandex-cloud/ydb-go-sdk/v2](https://github.com/yandex-cloud/ydb-go-sdk/tree/v2.11.2) доступен по [ссылке](../archive/example-go-v2.md). {% endnote %} +======= +>>>>>>> ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-go.md diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-java.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-java.md index 87780736137..72f47783a28 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-java.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-java.md @@ -94,10 +94,30 @@ private void describeTables() { } } ``` +{% include [steps/03_write_queries.md](steps/03_write_queries.md) %} + +Фрагмент кода, демонстрирующий выполнение запроса на запись/изменение данных: + +```java +private void upsertSimple() { + String query = String.format( + "PRAGMA TablePathPrefix(\"%s\");\n" + + "\n" + + "UPSERT INTO episodes (series_id, season_id, episode_id, title) VALUES\n" + + "(2, 6, 1, \"TBD\");", + database); + + TxControl txControl = TxControl.serializableRw().setCommitTx(true); + + execute(session -> session.executeDataQuery(query, txControl) + .join() + .toStatus()); +} +``` {% include [pragmatablepathprefix.md](auxilary/pragmatablepathprefix.md) %} -{% include [query_processing.md](steps/03_query_processing.md) %} +{% include [steps/04_query_processing.md](steps/04_query_processing.md) %} Для выполнения YQL-запросов используется метод `Session.executeDataQuery()`. SDK позволяет в явном виде контролировать выполнение транзакций и настраивать необходимый режим выполнения транзакций с помощью класса `TxControl`. @@ -127,17 +147,9 @@ private void selectSimple() { } ``` -{% include [results_processing.md](steps/04_results_processing.md) %} - -В качестве результатов выполнения запроса возвращается `result.getResultSet(0)`. -Фрагмент кода, приведенный ниже, демонстрирует вывод результатов запроса с помощью вспомогательного класса `TablePrinter`. +В результате исполнения запроса формируется объект класса `DataQueryResult`, который может содержать несколько выборок, получаемых методом `getResultSet( <index> )`. Так как запрос содержал только одну команду `SELECT`, то результат содержит только одну выборку под индексом `0`. -```java -System.out.println("\n--[ SelectSimple ]--"); -new TablePrinter(result.getResultSet(0)).print(); -``` - -Приведенный фрагмент кода при запуске выводит на консоль текст: +Для его вывода с форматированием псевдографикой применяется вспомогательноый класс `TablePrinter`. Приведенный фрагмент кода при запуске выводит на консоль текст: ```bash --[ SelectSimple ]-- @@ -148,28 +160,9 @@ new TablePrinter(result.getResultSet(0)).print(); +-----------+------------------+--------------------+ ``` -{% include [write_queries.md](steps/05_write_queries.md) %} -Фрагмент кода, демонстрирующий выполнение запроса на запись/изменение данных: -```java -private void upsertSimple() { - String query = String.format( - "PRAGMA TablePathPrefix(\"%s\");\n" + - "\n" + - "UPSERT INTO episodes (series_id, season_id, episode_id, title) VALUES\n" + - "(2, 6, 1, \"TBD\");", - database); - - TxControl txControl = TxControl.serializableRw().setCommitTx(true); - - execute(session -> session.executeDataQuery(query, txControl) - .join() - .toStatus()); -} -``` - -{% include [write_queries.md](steps/05_write_queries.md) %} +{% include [param_queries.md](steps/06_param_queries.md) %} Фрагмент кода, приведенный ниже, демонстрирует использование параметризованных запросов и класс `Params` для формирования параметров и передачи их методу `executeDataQuery`. @@ -438,4 +431,4 @@ private Status explicitTcl(Session session) { } ``` -{% include [error_handling.md](steps/50_error_handling.md) %} + diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-nodejs.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-nodejs.md index 1357f67976f..3d567a31ea9 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-nodejs.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-nodejs.md @@ -19,4 +19,3 @@ await session.streamExecuteScanQuery(` `, consumer, {'$value': Primitive.utf8('ttt')}); ``` -{% include [error_handling.md](steps/50_error_handling.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-php.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-php.md index b623b614a09..4542de04ddc 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-php.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-php.md @@ -31,4 +31,4 @@ $table = $ydb->table(); $session = $table->session(); ``` -{% include [error_handling.md](steps/50_error_handling.md) %} + diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/index.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/index.md index 19b04b8d1c3..ea1ae0d6e49 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/index.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/index.md @@ -1,30 +1,51 @@ # Тестовое приложение -В данном разделе разбирается код тестового приложения, реализованного с использованием YDB SDK на разных языках программирования. +В данном разделе разбирается код однотипного тестового приложения, реализованного с использованием YDB SDK на разных языках программирования: + +{% if oss %} +- C++ [https://github.com/ydb-platform/ydb/tree/main/ydb/public/sdk/cpp/examples/basic_example](https://github.com/ydb-platform/ydb/tree/main/ydb/public/sdk/cpp/examples/basic_example) +{% endif %} +- С# (.NET) [https://github.com/ydb-platform/ydb-dotnet-examples](https://github.com/ydb-platform/ydb-dotnet-examples) +- Go [https://github.com/ydb-platform/ydb-go-examples/tree/master/basic](https://github.com/ydb-platform/ydb-go-examples/tree/master/basic) +- Java [https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/maven_project](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/maven_project) +- Node.js [https://github.com/ydb-platform/ydb-nodejs-sdk/tree/master/examples/basic-example-v1](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/master/examples/basic-example-v1) +- Python [https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/basic_example_v1](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/basic_example_v1) + +Инструкции по скачиванию и запуску тестового приложения находятся в файле `readme.md` по приведенным выше ссылкам. Тестовое приложение выполняет следующие шаги: {% include [init.md](steps/01_init.md) %} +{% if oss %}[C++](../example-cpp.md#init) | {% endif %} [C# (.NET)](../example-dotnet.md#init) | [Go](../go/index.md#init) | [Java](../example-java.md#init) | Node.js | [PHP](../example-php.md#init) | [Python](../python/index.md#init) + {% include [create_table.md](steps/02_create_table.md) %} -{% include [query_processing.md](steps/03_query_processing.md) %} +{% if oss %}[C++](../example-cpp.md#create-table) | {% endif %} [C# (.NET)](../example-dotnet.md#create-table) | [Go](../go/index.md#create-table) | [Java](../example-java.md#create-table) | Node.js | PHP | [Python](../python/index.md#create-table) + +{% include [write_queries.md](steps/03_write_queries.md) %} + +{% if oss %}[C++](../example-cpp.md#write-queries) | {% endif %} [C# (.NET)](../example-dotnet.md#write-queries) | Go | [Java](../example-java.md#write-queries) | Node.js | PHP | [Python](../python/index.md#write-queries) -{% include [results_processing.md](steps/04_results_processing.md) %} +{% include [query_processing.md](steps/04_query_processing.md) %} -{% include [write_queries.md](steps/05_write_queries.md) %} +{% if oss %}[C++](../example-cpp.md#query-processing) | {% endif %} [C# (.NET)](../example-dotnet.md#query-processing) | [Go](../go/index.md#query-processing) | [Java](../example-java.md#query-processing) | Node.js | PHP | [Python](../python/index.md#query-processing) {% include [param_queries.md](steps/06_param_queries.md) %} -{% include [param_prep_queries.md](steps/07_param_prep_queries.md) %} +{% if oss %}[C++](../example-cpp.md#param-queries) | {% endif %} [C# (.NET)](../example-dotnet.md#param-queries) | [Go](../go/index.md#param-queries) | [Java](../example-java.md#param-queries) | Node.js | PHP | [Python](../python/index.md#param-queries) {% include [scan_query.md](steps/08_scan_query.md) %} +{% if oss %}C++ | {% endif %} [C# (.NET)](../example-dotnet.md#scan-query) | [Go](../go/index.md#scan-query) | [Java](../example-java.md#scan-query) | [Node.js](../example-nodejs.md#scan-query) | PHP | [Python](../python/index.md#scan-query) + {% include [multistep_transactions.md](steps/09_multistep_transactions.md) %} -{% include [transaction_control.md](steps/10_transaction_control.md) %} +{% if oss %}[C++](../example-cpp.md#multistep-transactions) | {% endif %} C# (.NET) | Go | [Java](../example-java.md#multistep-transactions) | Node.js | PHP | Python -{% include [error_handling.md](steps/50_error_handling.md) %} +{% include [transaction_control.md](steps/10_transaction_control.md) %} +{% if oss %}[C++](../example-cpp.md#tcl) | {% endif %} C# (.NET) | Go | [Java](../example-java.md#tcl) | Node.js | PHP | [Python](../python/index.md#tcl) +{% include [error_handling.md](steps/50_error_handling.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/pars_from_profile_hint.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/pars_from_profile_hint.md new file mode 100644 index 00000000000..7c59aee7112 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/pars_from_profile_hint.md @@ -0,0 +1,9 @@ +{% note info %} + +Если вы ранее проходили по статьям раздела документации "Начало работы", то необходимые параметры уже были вами использованы при [знакомстве с YDB CLI](../../../../getting_started/cli.md), и вы их можете получить из профиля: + +``` bash +{{ ydb-cli }} config profile get db1 +``` + +{% endnote %}
\ No newline at end of file diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/01_init.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/01_init.md index 7f4032c7985..11b242640cd 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/01_init.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/01_init.md @@ -1,4 +1,4 @@ -## Создание экземпляра драйвера, клиента и сессии {#driver-client-session-init} +## Инициализация соединения с базой данных {#init} Для взаимодействия с {{ ydb-short-name }} необходимо создать экземпляр драйвера, клиента и сессии: diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/02_create_table.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/02_create_table.md index e5014e43f26..38f3c112416 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/02_create_table.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/02_create_table.md @@ -1,2 +1,10 @@ -## Создание таблиц с помощью CrеateTable API {#create-table-api} +## Создание таблиц {#create-table} + +Выполняется создание таблиц, которые используются в дальнейших операциях тестового приложения. В результате исполнения шага в базе данных будут созданы таблицы модели данных справочника сериалов: + +- `series` - Сериалы +- `seasons` - Сезоны +- `episodes` - Эпизоды + +После создания вызывается метод получения информации об объекте схемы данных, и выводится результат его выполнения.
\ No newline at end of file diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/03_query_processing.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/03_query_processing.md deleted file mode 100644 index 516cc58a662..00000000000 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/03_query_processing.md +++ /dev/null @@ -1 +0,0 @@ -## Обработка запросов и транзакций {#query-processing} diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/03_write_queries.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/03_write_queries.md new file mode 100644 index 00000000000..15bbea5155f --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/03_write_queries.md @@ -0,0 +1,3 @@ +## Запись данных {#write-queries} + +Выполняется запись данных в созданные таблицы с использованием команды [`UPSERT`](../../../../../yql/reference/syntax/upsert_into.md) языка запросов [YQL](../../../../../yql/reference/index.md). Применяется режим передачи запроса на изменение данных с автоматическим подтверждением транзакции в одном запросе к серверу. diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/04_query_processing.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/04_query_processing.md new file mode 100644 index 00000000000..f0cb72d6049 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/04_query_processing.md @@ -0,0 +1,3 @@ +## Получение выборки данных {#query-processing} + +Выполняется запрос на получение выборки данных с использованием команды [`SELECT`](../../../../../yql/reference/syntax/select.md) языка запросов [YQL](../../../../../yql/reference/index.md). Демонстрируется обработка полученной выборки в приложении.
\ No newline at end of file diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/04_results_processing.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/05_results_processing.md index 6543f18e4d1..6543f18e4d1 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/04_results_processing.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/05_results_processing.md diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/05_write_queries.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/05_write_queries.md deleted file mode 100644 index d42c55dcdbf..00000000000 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/05_write_queries.md +++ /dev/null @@ -1 +0,0 @@ -## Запросы на запись и изменение данных {#write-queries} diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/06_param_queries.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/06_param_queries.md index e3fe3695f49..2886452e366 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/06_param_queries.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/06_param_queries.md @@ -1,7 +1,3 @@ ## Параметризованные запросы {#param-queries} -{% note warning "Использование параметров в запросах" %} - -Настоятельно рекомендуется использовать только параметризованные запросы. Это позволяет БД выполнить подготовительную работу по разбору и оптимизации запроса один раз для нескольких запросов, отличающихся только значениями параметров. - -{% endnote %} +Выполняется запрос к данным с использованием параметров. Этот вариант выполнения запросов является предпочтительным, так как позволяет серверу переиспользовать план исполнения запроса при последующих его вызовах, а также спасает от уязвимостей вида [SQL Injection](https://ru.wikipedia.org/wiki/Внедрение_SQL-кода). diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/08_scan_query.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/08_scan_query.md index 27a999b5621..8d0a4f5a95c 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/08_scan_query.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/08_scan_query.md @@ -1,3 +1,3 @@ ## Скан запросы {#scan-query} -Результатом выполнения [скан запроса](../../../../../concepts/scan_query.md) является стрим данных. Далее приведен пример обработки результата такого запроса. +Выполняется [скан запрос](../../../../../concepts/scan_query.md) данных, результатом исполнения которого является стрим. Стрим позволяет считать неограниченное количество строк и объем данных. diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/09_multistep_transactions.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/09_multistep_transactions.md index 8ac61053340..8d81ddece4c 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/09_multistep_transactions.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/09_multistep_transactions.md @@ -1,3 +1,3 @@ -## Многошаговые транзакции с промежуточной обработкой данных на стороне клиента {#multistep-transactions} +## Многошаговые транзакции {#multistep-transactions} -Фрагмент кода, приведенный ниже, демонстрирует возможность использования многошаговых транзакций, состоящих из нескольких запросов. Между выполнением запросов допустимо выполнение работы кода клиентского приложения. +Выполняется несколько команд в рамках одной многошаговой транзакции. Между выполнением запросов допустимо выполнение работы кода клиентского приложения. Использование транзакции позволяет гарантировать, что выполненные в её контексте выборки консистентны между собой. diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/10_transaction_control.md b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/10_transaction_control.md index a09135f02ce..d6ff389686a 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/10_transaction_control.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/steps/10_transaction_control.md @@ -1,3 +1,5 @@ -## Явное использование вызовов TCL Begin/Commit {#tcl-usage} +## Управление транзакциями {#tcl} -В большинстве случаев вместо явного использования [TCL](../../../../../concepts/transactions.md) вызовов Begin и Commit лучше использовать параметры контроля транзакций в вызовах execute. Это позволит избежать лишних обращений к {{ ydb-short-name }} и эффективней выполнять запросы. +Выполняются вызовы операторов управления транзакциями [TCL](../../../../../concepts/transactions.md) - Begin и Commit. + +В большинстве случаев вместо явного использования вызовов Begin и Commit лучше использовать параметры контроля транзакций в вызовах execute. Это позволит избежать лишних обращений к {{ ydb-short-name }} и эффективней выполнять запросы. diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/archive/example-go-v1.md b/ydb/docs/ru/core/reference/ydb-sdk/example/archive/example-go-v1.md index 66dc975f197..636aef5445d 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/archive/example-go-v1.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/archive/example-go-v1.md @@ -86,7 +86,7 @@ func describeTable(ctx context.Context, sp *table.SessionPool, path string) (err ) ``` -{% include [query_processing.md](../_includes/steps/03_query_processing.md) %} +{% include [query_processing.md](../_includes/steps/04_query_processing.md) %} Для выполнения YQL-запросов используется метод `Session.Execute()`. SDK позволяет в явном виде контролировать выполнение транзакций и настраивать необходимый режим выполнения транзакций с помощью класса ```TxControl```. @@ -135,7 +135,7 @@ if err != nil { } ``` -{% include [results_processing.md](../_includes/steps/04_results_processing.md) %} +{% include [results_processing.md](../_includes/steps/05_results_processing.md) %} Результат выполнения запроса: @@ -195,7 +195,7 @@ if err != nil { } ``` -{% include [results_processing.md](../_includes/steps/04_results_processing.md) %} +{% include [results_processing.md](../_includes/steps/08_scan_query.md) %} Результат выполнения запроса: diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/archive/example-go-v2.md b/ydb/docs/ru/core/reference/ydb-sdk/example/archive/example-go-v2.md index 38c38a1fb93..07c22e3ece0 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/archive/example-go-v2.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/archive/example-go-v2.md @@ -86,7 +86,7 @@ func describeTable(ctx context.Context, sp *table.SessionPool, path string) (err ) ``` -{% include [query_processing.md](../_includes/steps/03_query_processing.md) %} +{% include [query_processing.md](../_includes/steps/04_query_processing.md) %} Для выполнения YQL-запросов используется метод `Session.Execute()`. SDK позволяет в явном виде контролировать выполнение транзакций и настраивать необходимый режим выполнения транзакций с помощью класса ```TxControl```. @@ -131,7 +131,7 @@ if err != nil { } ``` -{% include [results_processing.md](../_includes/steps/04_results_processing.md) %} +{% include [results_processing.md](../_includes/steps/05_results_processing.md) %} Результат выполнения запроса: @@ -183,7 +183,7 @@ if err != nil { } ``` -{% include [results_processing.md](../_includes/steps/04_results_processing.md) %} +{% include [results_processing.md](../_includes/steps/08_scan_query.md) %} Результат выполнения запроса: diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/example-go.md b/ydb/docs/ru/core/reference/ydb-sdk/example/example-go.md deleted file mode 100644 index 3ece27c3e83..00000000000 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/example-go.md +++ /dev/null @@ -1,2 +0,0 @@ -{% include [example-go.md](_includes/example-go.md) %} - diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/example-python.md b/ydb/docs/ru/core/reference/ydb-sdk/example/example-python.md deleted file mode 100644 index 4d48b84332c..00000000000 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/example-python.md +++ /dev/null @@ -1,2 +0,0 @@ -{% include [example-python.md](_includes/example-python.md) %} - diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/go/_includes/run_custom.md b/ydb/docs/ru/core/reference/ydb-sdk/example/go/_includes/run_custom.md new file mode 100644 index 00000000000..b2fddd2503e --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/go/_includes/run_custom.md @@ -0,0 +1,25 @@ +Для выполнения примера с использованием любой доступной базы данных YDB вам потребуется знать [Эндпоинт](../../../../../concepts/connect.md#endpoint) и [Размещение базы данных](../../../../../concepts/connect.md#database). + +Если в базе данных включена аутентификация, то вам также понадобится выбрать [режим аутентификации](../../../../../concepts/connect.md#auth-modes) и получить секреты - токен или логин/пароль. + +Выполните команду по следующему образцу: + +``` bash +( export <auth_mode_var>="<auth_mode_value>" && cd ydb-go-examples && \ +go run ./basic -ydb="<endpoint>?database=<database>" ) +``` + +, где + +- `<endpoint>` - [Эндпоинт](../../../../../concepts/connect.md#endpoint) +- `<database>` - [Размещение базы данных](../../../../../concepts/connect.md#database) +- `<auth_mode_var`> - [Переменная окружения](../../../auth.md#env), определяющая режима аутентификации +- `<auth_mode_value>` - Значение параметра аутентификации для выбранного режима + +Например: +``` bash +( export YDB_ACCESS_TOKEN_CREDENTIALS="t1.9euelZqOnJuJlc..." && cd ydb-go-examples && \ +go run ./basic -ydb="grpcs://ydb.example.com:2135?database=/somepath/somelocation" ) +``` + +{% include [../../_includes/pars_from_profile_hint.md](../../_includes/pars_from_profile_hint.md) %}
\ No newline at end of file diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/go/_includes/run_docker.md b/ydb/docs/ru/core/reference/ydb-sdk/example/go/_includes/run_docker.md new file mode 100644 index 00000000000..5331a3f347a --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/go/_includes/run_docker.md @@ -0,0 +1,6 @@ +Для соединения с развернутой локальной базой данных YDB по сценарию [Docker](../../../../../getting_started/ydb_docker.md) в конфигурации по-умолчанию выполните следующую команду: + +``` bash +( export YDB_ANONYMOUS_CREDENTIALS=1 && cd ydb-go-examples && \ +go run ./basic -ydb="grpc://localhost:2136?database=/local" ) +``` diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/go/_includes/run_options.md b/ydb/docs/ru/core/reference/ydb-sdk/example/go/_includes/run_options.md new file mode 100644 index 00000000000..a637c6126b9 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/go/_includes/run_options.md @@ -0,0 +1,11 @@ +{% list tabs %} + +- Local Docker + + {% include [run_docker.md](run_docker.md) %} + +- Любая база данных + + {% include [run_custom.md](run_custom.md) %} + +{% endlist %} diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/go/index.md b/ydb/docs/ru/core/reference/ydb-sdk/example/go/index.md new file mode 100644 index 00000000000..dd2413e4724 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/go/index.md @@ -0,0 +1,272 @@ +# Приложение на Go + +На этой странице подробно разбирается код [тестового приложения](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/basic), использующего [Go SDK](https://github.com/ydb-platform/ydb-go-sdk/v3) {{ ydb-short-name }}. + +## Скачивание и запуск {#download} + +Приведенный ниже сценарий запуска использует [git](https://git-scm.com/downloads) и [Go](https://go.dev/doc/install). Предварительно должен быть установлен [YDB Go SDK](../../install.md). + +Создайте рабочую директорию и выполните в ней из командной строки команду клонирования репозитория с github.com: + +``` bash +git clone https://github.com/ydb-platform/ydb-go-examples/ +``` + +Далее из этой же рабочей директории выполните команду запуска тестового приложения, которая будет отличаться в зависимости от того к какой базе данных необходимо подключиться. + +{% include [run_options.md](_includes/run_options.md) %} + + + +{% include [init.md](../_includes/steps/01_init.md) %} + +Для работы с `YDB` в `go` следует импортировать пакет драйвера `ydb-go-sdk`: + +```go +import ( + // общие импорты + "context" + "path" + + // импорты пакетов ydb-go-sdk + "github.com/ydb-platform/ydb-go-sdk/v3" + "github.com/ydb-platform/ydb-go-sdk/v3/table" // для работы с table-сервисом + "github.com/ydb-platform/ydb-go-sdk/v3/table/options" // для работы с table-сервисом + "github.com/ydb-platform/ydb-go-sdk/v3/table/result" // для работы с table-сервисом + "github.com/ydb-platform/ydb-go-sdk/v3/table/result/named" // для работы с table-сервисом + "github.com/ydb-platform/ydb-go-sdk-auth-environ" // для аутентификации с использованием перменных окружения + "github.com/ydb-platform/ydb-go-yc" // для работы с YDB в Яндекс Облаке +) +``` + +Фрагмент кода приложения для инициализации драйвера: + +```go +ctx := context.Background() +// строка подключения +dsn := "grpcs://ydb.serverless.yandexcloud.net:2135/?database=/ru-central1/b1g8skpblkos03malf3s/etn01f8gv9an9sedo9fu" +// IAM-токен +token := "t1.9euelZrOy8aVmZKJm5HGjceMkMeVj-..." +// создаем объект подключения db, является входной точкой для сервисов YDB +db, err := ydb.New( + ctx, + ydb.WithConnectionString(dsn), +// yc.WithInternalCA(), // используем сертификаты Яндекс Облака + ydb.WithAccessTokenCredentials(token), // аутентификация с помощью токена +// ydb.WithAnonimousCredentials(token), // анонимная аутентификация (например, в docker ydb) +// yc.WithMetadataCredentials(token), // аутентификация изнутри виртуальной машины в Яндекс Облаке или из Яндекс Функции +// yc.WithServiceAccountKeyFileCredentials("~/.ydb/sa.json"), // аутентификация в Яндекс Облаке с помощью файла сервисного аккаунта +// environ.WithEnvironCredentials(ctx), // аутентификация с использованием переменных окружения +) +if err != nil { + // обработка ошибки подключения +} +// закрытие драйвера по окончании работы программы обязательно +defer func() { + _ = db.Close(ctx) +} +``` + +Объект `db` является входной точкой для работы с сервисами `YDB`. +Для работы сервисом таблиц следует использовать клиента table-сервиса `db.Table()`. +Клиент table-сервиса предоставляет `API` для выполнения запросов над таблицами. +Наиболее востребован метод `db.Table().Do(ctx, op)`, который реализует фоновое создание сессий и повторные попытки выполнить пользовательскую операцию `op`, в которую пользовательскому коду отдается подготовленная сессия. +Сессия имеет исчерпывающее `API`, позволяющее выполнять `DDL`, `DML`, `DQL` и `TCL` запросы. + +{% include [steps/02_create_table.md](../_includes/steps/02_create_table.md) %} + +Для создания таблиц используется метод `table.Session.CreateTable()`: + +```go +err = db.Table().Do( + ctx, + func(ctx context.Context, s table.Session) (err error) { + return s.CreateTable(ctx, path.Join(db.Name(), "series"), + options.WithColumn("series_id", types.Optional(types.TypeUint64)), + options.WithColumn("title", types.Optional(types.TypeUTF8)), + options.WithColumn("series_info", types.Optional(types.TypeUTF8)), + options.WithColumn("release_date", types.Optional(types.TypeDate)), + options.WithColumn("comment", types.Optional(types.TypeUTF8)), + options.WithPrimaryKeyColumn("series_id"), + ) + }, +) +if err != nil { + // обработка ситуации, когда не удалось выполнить запрос +} +``` + +С помощью метода `table.Session.DescribeTable()` можно вывести информацию о структуре таблицы и убедиться, что она успешно создалась: + +```go +err = db.Table().Do( + ctx, + func(ctx context.Context, s table.Session) (err error) { + desc, err := s.DescribeTable(ctx, path.Join(db.Name(), "series")) + if err != nil { + return + } + log.Printf("> describe table: %s\n", tableName) + for _, c := range desc.Columns { + log.Printf(" > column, name: %s, %s\n", c.Type, c.Name) + } + return + } +) +if err != nil { + // обработка ситуации, когда не удалось выполнить запрос +} +``` + +{% include [steps/04_query_processing.md](../_includes/steps/04_query_processing.md) %} + +Для выполнения YQL-запросов используется метод `table.Session.Execute()`. +SDK позволяет в явном виде контролировать выполнение транзакций и настраивать необходимый режим выполнения транзакций с помощью структуры `table.TxControl`. + +```go +var ( + readTx = table.TxControl( + table.BeginTx( + table.WithOnlineReadOnly(), + ), + table.CommitTx(), + ) +) +err := db.Table().Do( + ctx, + func(ctx context.Context, s table.Session) (err error) { + var ( + res result.Result + id *uint64 // указатель - для опциональных результатов + title *string // указатель - для опциональных результатов + date *time.Time // указатель - для опциональных результатов + ) + _, res, err = s.Execute( + ctx, + readTx, + ` + DECLARE $seriesID AS Uint64; + SELECT + series_id, + title, + release_date + FROM + series + WHERE + series_id = $seriesID; + `, + table.NewQueryParameters( + table.ValueParam("$seriesID", types.Uint64Value(1)), // подстановка в условие запроса + ), + options.WithQueryCachePolicy( + options.WithQueryCachePolicyKeepInCache(), // включаем серверный кэш скомпилированных запросов + ), + ) + if err != nil { + return err + } + defer func() { + _ = res.Close() // закрытие result'а обязательно + }() + log.Printf("> select_simple_transaction:\n") + for res.NextResultSet(ctx) { + for res.NextRow() { + // в ScanNamed передаем имена колонок из строки сканирования, + // адреса (и типы данных), куда следует присвоить результаты запроса + err = res.ScanNamed( + named.Optional("series_id", &id), + named.Optional("title", &title), + named.Optional("release_date", &date), + ) + if err != nil { + return err + } + log.Printf( + " > %d %s %s\n", + *id, *title, *date, + ) + } + } + return res.Err() + }, +) +if err != nil { + // обработка ошибки выполнения запроса +} +``` + +{% include [scan_query.md](../_includes/steps/08_scan_query.md) %} + +Для выполнения scan-запросов используется метод `table.Session.StreamExecuteScanQuery()`. + +```go +var ( + query = ` + DECLARE $series AS List<UInt64>; + SELECT series_id, season_id, title, first_aired + FROM seasons + WHERE series_id IN $series + ` + res result.StreamResult +) +err = c.Do( + ctx, + func(ctx context.Context, s table.Session) (err error) { + res, err = s.StreamExecuteScanQuery(ctx, query, + table.NewQueryParameters( + table.ValueParam("$series", + types.ListValue( + types.Uint64Value(1), + types.Uint64Value(10), + ), + ), + ), + ) + if err != nil { + return err + } + defer func() { + _ = res.Close() // закрытие result'а обязательно + }() + var ( + seriesID uint64 + seasonID uint64 + title string + date time.Time + ) + log.Print("\n> scan_query_select:") + for res.NextResultSet(ctx) { + if err = res.Err(); err != nil { + return err + } + for res.NextRow() { + // named.OptionalOrDefault позволяет "развернуть" опциональные + // результаты или использовать дефолтное значение типа go + err = res.ScanNamed( + named.OptionalOrDefault("series_id", &seriesID), + named.OptionalOrDefault("season_id", &seasonID), + named.OptionalOrDefault("title", &title), + named.OptionalOrDefault("first_aired", &date), + ) + if err != nil { + return err + } + log.Printf("# Season, SeriesId: %d, SeasonId: %d, Title: %s, Air date: %s", seriesID, seasonID, title, date) + } + } + return res.Err() + }, +) +if err != nil { + // обработка ошибки выполнения запроса +} +``` + + +{% note info %} + +Разбор кода тестового приложения, использующего архивные версии Go SDK: + - [github.com/yandex-cloud/ydb-go-sdk](https://github.com/yandex-cloud/ydb-go-sdk/tree/v1.5.1) доступен по [ссылке](../archive/example-go-v1.md), + - [github.com/yandex-cloud/ydb-go-sdk/v2](https://github.com/yandex-cloud/ydb-go-sdk/tree/v2.11.2) доступен по [ссылке](../archive/example-go-v2.md). + +{% endnote %} diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/python/_includes/run_custom.md b/ydb/docs/ru/core/reference/ydb-sdk/example/python/_includes/run_custom.md new file mode 100644 index 00000000000..52a5b679162 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/python/_includes/run_custom.md @@ -0,0 +1,25 @@ +Для выполнения примера с использованием любой доступной базы данных YDB вам потребуется знать [Эндпоинт](../../../../../concepts/connect.md#endpoint) и [Размещение базы данных](../../../../../concepts/connect.md#database). + +Если в базе данных включена аутентификация, то вам также понадобится выбрать [режим аутентификации](../../../../../concepts/connect.md#auth-modes) и получить секреты - токен или логин/пароль. + +Выполните команду по следующему образцу: + +``` bash +( export <auth_mode_var>="<auth_mode_value>" && \ +python3 ydb-python-sdk/examples/basic_example_v1/ -e <endpoint> -d <database> ) +``` + +, где + +- `<endpoint>` - [Эндпоинт](../../../../../concepts/connect.md#endpoint) +- `<database>` - [Размещение базы данных](../../../../../concepts/connect.md#database) +- `<auth_mode_var`> - [Переменная окружения](../../../auth.md#env), определяющая режима аутентификации +- `<auth_mode_value>` - Значение параметра аутентификации для выбранного режима + +Например: +``` bash +( export YDB_ACCESS_TOKEN_CREDENTIALS="t1.9euelZqOnJuJlc..." && \ +python3 ydb-python-sdk/examples/basic_example_v1/ -e grpcs://ydb.example.com:2135 -d /path/db ) +``` + +{% include [../../_includes/pars_from_profile_hint.md](../../_includes/pars_from_profile_hint.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/python/_includes/run_docker.md b/ydb/docs/ru/core/reference/ydb-sdk/example/python/_includes/run_docker.md new file mode 100644 index 00000000000..3b6f39d006e --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/python/_includes/run_docker.md @@ -0,0 +1,6 @@ +Для соединения с развернутой локальной базой данных YDB по сценарию [Docker](../../../../../getting_started/ydb_docker.md) в конфигурации по-умолчанию выполните следующую команду: + +``` bash +( export YDB_ANONYMOUS_CREDENTIALS=1 && \ +python3 ydb-python-sdk/examples/basic_example_v1/ -e grpc://localhost:2136 -d /local ) +``` diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/python/_includes/run_options.md b/ydb/docs/ru/core/reference/ydb-sdk/example/python/_includes/run_options.md new file mode 100644 index 00000000000..a637c6126b9 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/python/_includes/run_options.md @@ -0,0 +1,11 @@ +{% list tabs %} + +- Local Docker + + {% include [run_docker.md](run_docker.md) %} + +- Любая база данных + + {% include [run_custom.md](run_custom.md) %} + +{% endlist %} diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-python.md b/ydb/docs/ru/core/reference/ydb-sdk/example/python/index.md index 80436ffc04e..41a3f448360 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/_includes/example-python.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/python/index.md @@ -2,7 +2,22 @@ На этой странице подробно разбирается код [тестового приложения](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/basic_example_v1), доступного в составе [Python SDK](https://github.com/yandex-cloud/ydb-python-sdk) {{ ydb-short-name }}. -{% include [init.md](steps/01_init.md) %} +## Скачивание и запуск {#download} + +Приведенный ниже сценарий запуска использует [git](https://git-scm.com/downloads) и [Python3](https://www.python.org/downloads/). Предварительно должен быть установлен [YDB Python SDK](../../install.md). + +Создайте рабочую директорию и выполните в ней из командной строки команды клонирования репозитория с github.com и установки необходимых пакетов Python: + +``` bash +git clone https://github.com/ydb-platform/ydb-python-sdk.git +python3 -m pip install iso8601 +``` + +Далее из этой же рабочей директории выполните команду запуска тестового приложения, которая будет отличаться в зависимости от того к какой базе данных необходимо подключиться. + +{% include [run_options.md](_includes/run_options.md) %} + +{% include [init.md](../_includes/steps/01_init.md) %} Фрагмент кода приложения для инициализации драйвера: @@ -28,7 +43,7 @@ def run(endpoint, database, path): session = driver.table_client.session().create() ``` -{% include [create_table.md](steps/02_create_table.md) %} +{% include [create_table.md](../_includes/steps/02_create_table.md) %} Для создания таблиц используется метод `session.create_table()`: @@ -64,10 +79,25 @@ def describe_table(session, path, name): ('column, name:', 'series_info', ',', 'type_id: UTF8') ('column, name:', 'release_date', ',', 'type_id: UINT64') ``` +{% include [steps/03_write_queries.md](../_includes/steps/03_write_queries.md) %} + +Фрагмент кода, демонстрирующий выполнение запроса на запись/изменение данных: + +```python +def upsert_simple(session, path): + session.transaction().execute( + """ + PRAGMA TablePathPrefix("{}"); + UPSERT INTO episodes (series_id, season_id, episode_id, title) VALUES + (2, 6, 1, "TBD"); + """.format(path), + commit_tx=True, + ) +``` -{% include [pragmatablepathprefix.md](auxilary/pragmatablepathprefix.md) %} +{% include [pragmatablepathprefix.md](../_includes/auxilary/pragmatablepathprefix.md) %} -{% include [create_table.md](steps/03_query_processing.md) %} +{% include [steps/04_query_processing.md](../_includes/steps/04_query_processing.md) %} Для выполнения YQL-запросов используется метод `session.transaction().execute()`. SDK позволяет в явном виде контролировать выполнение транзакций и настраивать необходимый режим выполнения транзакций с помощью класса `TxControl`. @@ -96,40 +126,15 @@ def select_simple(session, path): return result_sets[0] ``` -{% include [results_processing.md](steps/04_results_processing.md) %} - -В качестве результата выполнения запроса возвращается `result_set`: - -```python -print("\n> select_simple_transaction:") -for row in result_sets[0].rows: - print("series, id: ", row.series_id, ", title: ", row.title, ", release date: ", row.release_date) -``` - -Приведенный фрагмент кода при запуске выводит на консоль текст: +В качестве результата выполнения запроса возвращается `result_set`, итерирование по которому выводит на консоль текст: ```bash > SelectSimple: series, Id: 1, title: IT Crowd, Release date: 2006-02-03 ``` -{% include [write_queries.md](steps/05_write_queries.md) %} - -Фрагмент кода, демонстрирующий выполнение запроса на запись/изменение данных: - -```python -def upsert_simple(session, path): - session.transaction().execute( - """ - PRAGMA TablePathPrefix("{}"); - UPSERT INTO episodes (series_id, season_id, episode_id, title) VALUES - (2, 6, 1, "TBD"); - """.format(path), - commit_tx=True, - ) -``` -{% include [param_prep_queries.md](steps/07_param_prep_queries.md) %} +{% include [param_prep_queries.md](../_includes/steps/07_param_prep_queries.md) %} ```python def select_prepared(session, path, series_id, season_id, episode_id): @@ -169,7 +174,7 @@ def select_prepared(session, path, series_id, season_id, episode_id): ('episode title:', u'To Build a Better Beta', ', air date:', '2016-06-05') ``` -{% include [scan_query.md](steps/08_scan_query.md) %} +{% include [scan_query.md](../_includes/steps/08_scan_query.md) %} ```python def executeScanQuery(driver): @@ -190,7 +195,7 @@ def executeScanQuery(driver): break ``` -{% include [transaction_control.md](steps/10_transaction_control.md) %} +{% include [transaction_control.md](../_includes/steps/10_transaction_control.md) %} Фрагмент кода, демонстрирующий явное использование вызовов `transaction().begin()` и `tx.Commit()`: @@ -224,4 +229,3 @@ def explicit_tcl(session, path, series_id, season_id, episode_id): tx.commit() ``` -{% include [error_handling.md](steps/50_error_handling.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-sdk/example/toc_i.yaml b/ydb/docs/ru/core/reference/ydb-sdk/example/toc_i.yaml index e0111cda2d2..a030cd21a25 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/example/toc_i.yaml +++ b/ydb/docs/ru/core/reference/ydb-sdk/example/toc_i.yaml @@ -3,11 +3,10 @@ items: href: index.md - name: C++ href: example-cpp.md - when: oss - name: C# (.NET) href: example-dotnet.md - name: Go - href: example-go.md + href: go/index.md - name: Java href: example-java.md - name: Node.js @@ -15,7 +14,7 @@ items: - name: PHP href: example-php.md - name: Python - href: example-python.md + href: python/index.md - name: Архив items: - name: Go v1 diff --git a/ydb/docs/ru/core/reference/ydb-sdk/index.md b/ydb/docs/ru/core/reference/ydb-sdk/index.md index 83b2b05fc1a..53ac869580c 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/index.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/index.md @@ -1,3 +1,3 @@ -{% include [intro.md](_includes/index/intro.md) %} +{% include [index.md](_includes/index.md) %} + -{% include [examples.md](_includes/index/examples.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-sdk/install.md b/ydb/docs/ru/core/reference/ydb-sdk/install.md new file mode 100644 index 00000000000..898729dbbe7 --- /dev/null +++ b/ydb/docs/ru/core/reference/ydb-sdk/install.md @@ -0,0 +1,2 @@ + +{% include [install.md](_includes/install.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-sdk/toc_i.yaml b/ydb/docs/ru/core/reference/ydb-sdk/toc_i.yaml index 1eb6a104af7..b75c28691c3 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/toc_i.yaml +++ b/ydb/docs/ru/core/reference/ydb-sdk/toc_i.yaml @@ -1,6 +1,8 @@ items: - name: Обзор href: index.md + - name: Установка + href: install.md - name: Аутентификация href: auth.md - name: Тестовое приложение |