SDK

Yandex Query is based on YDB external tables, hence, you need the YDB SDK to work with the service.

The YDB SDK enables you to use Yandex Query in various programming languages:

• Java SDK
• Python SDK
• Go SDK
• C++ SDK
• .NET SDK
• Rust SDK

For the full list of the YDB SDKs, see the ydb-platform page on GitHub.

All examples below use the Python SDK. SDKs for other development languages work similarly, so you can apply all the approaches to them right down to the implementation of each individual SDK.

AuthenticationAuthentication

Yandex Query is a fully managed service that uses the IAM mechanisms for authentication.

You can authenticate using:

• Authorized keys
• Static keys
• IAM token
• VM metadata

For any of the above-listed authentication methods, you can use the existing SDK methods.

In this example, we will use an authorized key. To create an authorized key, follow these steps:

1. Create a service account with the yq.editor role.
2. Create an authorized access key for the service account you created. Save the authorized access key to a JSON file.

ConnectionConnection

To connect to Yandex Query, you need to create an object named ydb.Driver specifying the connection parameters and authentication data:

auth_key_file = "<path_to_auth_key_file>"

with ydb.Driver(endpoint="grpcs://grpc.yandex-query.cloud.yandex.net:2135",
                database="/<folder_id>",
                credentials=ydb.iam.ServiceAccountCredentials.from_file(auth_key_file)) as driver:
        driver.wait(timeout=5, fail_fast=True)

Where:

• endpoint: Endpoint for connecting to the data source. Yandex Query uses a fixed address, grpcs://grpc.yandex-query.cloud.yandex.net:2135.
• database: ID of the folder you want to run queries in. You must include the / prefix before the folder ID.
• credentials: Credentials for authentication in Yandex Cloud.

Running a queryRunning a query

To run a query, you must open a session to Yandex Query and run an SQL query in it:

with ydb.SessionPool(driver) as pool:

    def callee(session):
        result_sets = session.transaction(ydb.SerializableReadWrite()).execute(
            """
            SELECT 'Hello, world!' AS message;
            """,
            commit_tx=True,
        )
        ...

    return pool.retry_operation_sync(callee)

YDB supports a number of query execution methods: normal, scripting request, scan request, and query request.

Getting query resultsGetting query results

You can get return values as follows:

for row in result_sets[0].rows:
    print(row.message)

return result_sets[0]

Full exampleFull example

Below is an example of how to use Yandex Query with the YDB Python SDK.

python3 -m pip install ydb
python3 -m pip install requests
python3 -m pip install "ydb[yc]"

import ydb
import ydb.iam

auth_key_file = "<path_to_auth_key_file>"

def main():
    with ydb.Driver(endpoint="grpcs://grpc.yandex-query.cloud.yandex.net:2135",
                    database="/<folder_id>",
                    credentials=ydb.iam.ServiceAccountCredentials.from_file(auth_key_file)) as driver:
            driver.wait(timeout=5, fail_fast=True)

            with ydb.SessionPool(driver) as pool:

                def callee(session):
                    # New transaction in serializable read write mode.
                    # If query successfully completed you will get result sets.
                    # Otherwise exception will be raised.
                    result_sets = session.transaction(ydb.SerializableReadWrite()).execute(
                        """
                        select 'Hello, world!' as message
                        """,
                        commit_tx=True,
                    )
                    for row in result_sets[0].rows:
                        print(row.message)

                pool.retry_operation_sync(callee)


if __name__ == "__main__":
     main()