如何使用Yandex YDB SDK为表字段添加UNIQUE约束？

YDB本身不支持关系型数据库中直接给字段添加UNIQUE关键字的约束方式，而是通过**创建唯一全局二级索引（GSI）**来实现等效的唯一约束效果。以下是具体的实现思路和代码示例：

核心原理 #

YDB的唯一二级索引会强制要求索引字段（或字段组合）的值在全局范围内唯一，当插入/更新数据时如果出现重复值，SDK会抛出约束违反的错误，以此达到唯一约束的目的。

实现方式 #

方式1：使用SDK的TableDescription和IndexDescription API #

这种方式通过SDK提供的面向对象API创建表和唯一索引：

const { Driver, TableDescription, Column, Type, IndexDescription } = require('ydb-sdk');

async function initUserTableWithUniqueEmail() {
    // 初始化YDB驱动（替换为你的配置）
    const driver = new Driver({
        endpoint: 'grpc://your-ydb-endpoint:2136',
        database: '/your/ydb/database/path',
        credentials: { /* 你的认证凭证，比如ServiceAccountCredentials */ }
    });

    await driver.ready();
    const session = await driver.createSession();

    try {
        // 1. 创建基础用户表
        const userTable = new TableDescription()
            .addColumn(new Column('user_id', Type.UINT64))
            .addColumn(new Column('email', Type.STRING))
            .addColumn(new Column('nickname', Type.STRING))
            .setPrimaryKeys(['user_id']);

        await session.createTable('/db/users', userTable);

        // 2. 创建唯一索引，约束email字段全局唯一
        const uniqueEmailIndex = new IndexDescription()
            .setName('idx_unique_user_email')
            .addIndexColumns(['email'])
            .setUnique(true); // 关键：开启索引唯一性

        await session.createIndex('/db/users', uniqueEmailIndex);

        console.log("表与唯一索引创建完成");
    } catch (err) {
        console.error("创建失败:", err);
    } finally {
        await session.close();
        await driver.destroy();
    }
}

initUserTableWithUniqueEmail();

方式2：直接执行YQL DDL语句 #

如果更熟悉SQL语法，可以直接执行YQL语句来创建表和唯一索引：

const { Driver, Session } = require('ydb-sdk');

async function createTableWithUniqueConstraint() {
    const driver = new Driver({
        endpoint: 'grpc://your-ydb-endpoint:2136',
        database: '/your/ydb/database/path',
        credentials: { /* 你的认证凭证 */ }
    });

    await driver.ready();
    const session = await driver.createSession();

    try {
        const yqlQuery = `
            CREATE TABLE users (
                user_id Uint64,
                email String,
                nickname String,
                PRIMARY KEY (user_id)
            );

            -- 创建唯一索引，实现email字段的唯一约束
            CREATE UNIQUE INDEX idx_unique_user_email ON users (email);
        `;

        await session.executeQuery(yqlQuery);
        console.log("表与唯一索引创建完成");
    } catch (err) {
        console.error("创建失败:", err);
    } finally {
        await session.close();
        await driver.destroy();
    }
}

createTableWithUniqueConstraint();

额外说明 #

• 可以创建多字段组合的唯一索引，比如CREATE UNIQUE INDEX idx_unique_email_nickname ON users (email, nickname);，这样会强制email+nickname的组合值唯一。
• 若需要取消唯一约束，只需删除对应的索引：DROP INDEX idx_unique_user_email ON users;
• 当插入或更新数据违反唯一约束时，SDK会抛出包含PRECONDITION_FAILED状态码的错误，你可以捕获该错误并处理业务逻辑。

内容的提问来源于stack exchange，提问作者George Golovchiner