ydb-table

name

ydb-table

description

Writing and auditing code that runs YQL against YDB tables. Use when the user writes a query, designs a table or primary key, reads an `EXPLAIN`, or asks to review Java (ydb-java-sdk, ydb-jdbc-driver, Hibernate, Spring Data JPA), Go (`ydb-go-sdk/v3`), or C++ (`ydb-cpp-sdk`) application code that talks to YDB. Triggers on YQL keywords (`UPSERT`, `SELECT`, `DECLARE`, `AS_TABLE`, `VIEW <index>`, `CREATE TABLE`, `ALTER TABLE`, `EXPLAIN`), on the `BulkUpsert` SDK API, on JDBC / Hibernate / Spring symbols (`JpaRepository`, `findAllById`, `saveAll`, `deleteAllByIdInBatch`, `hibernate.jdbc.batch_size`, `@Version`, `@Retryable`, `SQLRecoverableException`, `SQLTransientException`), on `ydb-go-sdk/v3` symbols (`ydb.Open`, `db.Query().Do`, `db.Query().DoTx`, `db.Table().Do`, `query.WithIdempotent`, `query.WithCommit`, `query.WithStatsMode`, `query.Stats`, `query.StatsModeBasic`, `result.Close`, `ydb.WithLazyTx`, `ydb.ParamsBuilder`, `s.BeginTransaction`, `table.TxControl`, `table.BeginTx`, `BulkUpsertDataRows`, `balancers.PreferLocalDC`, `balancers.PreferNearestDC`), on `ydb-cpp-sdk` symbols (`#include <ydb-cpp-sdk/client/`, `NYdb::TDriver`, `TDriverConfig`, `NYdb::NQuery::TQueryClient`, `NYdb::NTable::TTableClient`, `RetryQuerySync`, `RetryOperationSync`, `TRetryOperationSettings`, `TParamsBuilder`, `TTxControl`, `TValueBuilder`, `TResultSetParser`, `StreamExecuteQuery`, `BulkUpsert`, `ExecuteSchemeQuery`, `CreateFromEnvironment`, `GetValueSync`, `find_package(ydb-cpp-sdk`, `YDB-CPP-SDK::`), on flaky empty/zero query stats right after `Query` returns, on YDB transaction-mode names (`SerializableRW`, `SnapshotRO`), and on PostgreSQL / MySQL → YDB conversion prompts. For other SDKs (Python, C#) this skill covers only the YQL / schema / transaction-mode side; SDK-specific guidance for those languages is not in this skill yet — say so and point at upstream docs.

YDB Table

Writing YQL against YDB tables, designing schemas to back those queries, and auditing application code that runs them.

Workflow

1. Classify the task. Write a new query or schema, audit existing code, convert from another SQL dialect, or read an EXPLAIN.
2. Load sources per the table below.
3. Do the work. When auditing, cite RULE-JV-NN, RULE-GO-NN, or RULE-CPP-NN. C++ audits: never empty, never rule-ID-only — use the 4-part format in rules/embed/cpp.md (ID + diagnosis in sentence 1, then trigger, failure mode, fix).

Load sources

Task	Files to consult
Reads, writes, transaction modes, batch vs bulk	references/working-with-data.md
Writing Java application code against YDB	references/embed/java.md
Auditing Java application code against YDB	rules/embed/java.md
Writing Go application code against YDB	references/embed/go.md
Auditing Go application code against YDB	rules/embed/go.md
Writing C++ application code against YDB	references/embed/cpp.md
Auditing C++ application code against YDB	rules/embed/cpp.md
Schema design — primary key shape, partitioning	../ydb-core/SKILL.md#schema-basics
YQL syntax, built-in functions, pragmas	https://ydb.tech/docs/en/yql/reference/ — do not reproduce the spec from memory

Content rules

• Always parameterize: bind values through the SDK's typed parameter API (e.g. ydb.ParamsBuilder() in Go, TParamsBuilder in C++, PreparedStatement in JDBC), do not concatenate them into the query text. Plan-cache reuse depends on it; concatenated literals miss the cache. A leading DECLARE block in the query body is optional in modern YDB — scalar parameter types are inferred from the bound values — and earns its place on compound shapes (List<Struct<...>>) or as an explicit caller contract.
• Prefer the Query Service over the deprecated Table Service for new code.
• When converting from another SQL dialect, surface where YDB diverges — primary keys are partition keys, no SERIAL / AUTO_INCREMENT, JOIN behavior and built-in function names differ — rather than producing code that happens to parse.
• Don't fabricate YQL syntax, built-in names, or SDK symbols. If the loaded sources don't cover the question, link the relevant page under https://ydb.tech/docs/en/yql/reference/ and state the uncertainty.