Couchbase Scope与Collection #

一、概述 #

1.1 什么是Scope和Collection #

Scope和Collection是Couchbase 7.0引入的新特性，用于在Bucket内部组织数据：

  • Scope（作用域）：类似于关系数据库中的Schema，用于逻辑分组
  • Collection（集合）：类似于关系数据库中的Table，存储具体的文档

1.2 层级结构 #

text 
Cluster（集群）
└── Bucket（存储桶）- 物理存储单元
    └── Scope（作用域）- 逻辑分组
        └── Collection（集合）- 文档容器
            └── Document（文档）- 数据记录

1.3 与关系数据库对比 #

Couchbase 关系数据库 说明
Cluster Database Server 数据库服务器
Bucket Database 数据库
Scope Schema 模式
Collection Table 表
Document Row 行

1.4 默认结构 #

每个Bucket创建时自动包含：

text 
my-bucket
├── _default Scope
│   └── _default Collection
└── (可创建更多Scope和Collection)

二、Scope操作 #

2.1 创建Scope #

N1QL创建：

sql 
CREATE SCOPE `my-bucket`.`my-scope`;

CREATE SCOPE `my-bucket`.`my-scope` IF NOT EXISTS;

REST API创建：

bash 
curl -X POST http://localhost:8091/pools/default/buckets/my-bucket/scopes \
    -u Administrator:your-password \
    -d name=my-scope

SDK创建（Python）：

python 
from couchbase.cluster import Cluster, ClusterOptions
from couchbase.auth import PasswordAuthenticator

cluster = Cluster(
    'couchbase://localhost',
    ClusterOptions(PasswordAuthenticator('Administrator', 'password'))
)

bucket = cluster.bucket('my-bucket')
bucket.collections().create_scope('my-scope')

2.2 查看Scope #

查看所有Scope：

sql 
SELECT * FROM system:scopes
WHERE bucket_id = 'my-bucket';

命令行查看：

bash 
/opt/couchbase/bin/couchbase-cli bucket-get \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --bucket my-bucket \
    --json | jq '.scopes'

2.3 删除Scope #

sql 
DROP SCOPE `my-bucket`.`my-scope`;

DROP SCOPE `my-bucket`.`my-scope` IF EXISTS;

注意：删除Scope会删除其下所有Collection和文档！

三、Collection操作 #

3.1 创建Collection #

N1QL创建：

sql 
CREATE COLLECTION `my-bucket`.`my-scope`.`users`;

CREATE COLLECTION `my-bucket`.`my-scope`.`users` IF NOT EXISTS;

REST API创建：

bash 
curl -X POST http://localhost:8091/pools/default/buckets/my-bucket/scopes/my-scope/collections \
    -u Administrator:your-password \
    -d name=users

SDK创建（Python）：

python 
bucket.collections().create_collection('users', 'my-scope')

3.2 查看Collection #

查看所有Collection：

sql 
SELECT * FROM system:keyspaces
WHERE bucket_id = 'my-bucket' AND scope_id = 'my-scope';

查看指定Bucket下所有Collection：

sql 
SELECT 
    name,
    bucket_id,
    scope_id
FROM system:keyspaces
WHERE bucket_id = 'my-bucket';

3.3 删除Collection #

sql 
DROP COLLECTION `my-bucket`.`my-scope`.`users`;

DROP COLLECTION `my-bucket`.`my-scope`.`users` IF EXISTS;

四、完整路径引用 #

4.1 引用格式 #

sql 
SELECT * FROM `bucket-name`.`scope-name`.`collection-name`;

4.2 示例 #

sql 
SELECT * FROM `my-bucket`.`_default`.`_default` LIMIT 5;

SELECT * FROM `my-bucket`.`production`.`users` WHERE type = 'user';

SELECT * FROM `my-bucket`.`development`.`test_data` LIMIT 10;

4.3 使用反引号 #

当名称包含特殊字符时需要使用反引号：

sql 
SELECT * FROM `my-bucket`.`my-scope`.`my-collection`;

SELECT * FROM `my-bucket`.`scope-with-dash`.`collection_name`;

五、查询上下文 #

5.1 设置查询上下文 #

使用SET命令设置默认查询上下文：

sql 
SET query_context = `my-bucket`.`my-scope`;

设置后可以简化查询：

sql 
SELECT * FROM `users` LIMIT 5;

5.2 CBQ中设置 #

sql 
\SET -query_context `my-bucket`.`my-scope`;

SELECT * FROM `users` LIMIT 5;

5.3 SDK中设置 #

python 
from couchbase.options import QueryOptions

result = cluster.query(
    'SELECT * FROM `users` LIMIT 5',
    QueryOptions(query_context='my-bucket.my-scope')
)

六、实际应用示例 #

6.1 电商系统数据组织 #

text 
ecommerce-bucket
├── catalog Scope
│   ├── products（产品）
│   ├── categories（分类）
│   └── brands（品牌）
├── orders Scope
│   ├── orders（订单）
│   ├── order_items（订单项）
│   └── payments（支付）
├── users Scope
│   ├── users（用户）
│   ├── addresses（地址）
│   └── preferences（偏好）
└── analytics Scope
    ├── page_views（页面访问）
    ├── search_logs（搜索日志）
    └── recommendations（推荐）

创建结构：

sql 
CREATE SCOPE `ecommerce`.`catalog`;
CREATE SCOPE `ecommerce`.`orders`;
CREATE SCOPE `ecommerce`.`users`;
CREATE SCOPE `ecommerce`.`analytics`;

CREATE COLLECTION `ecommerce`.`catalog`.`products`;
CREATE COLLECTION `ecommerce`.`catalog`.`categories`;
CREATE COLLECTION `ecombase`.`catalog`.`brands`;

CREATE COLLECTION `ecommerce`.`orders`.`orders`;
CREATE COLLECTION `ecommerce`.`orders`.`order_items`;
CREATE COLLECTION `ecommerce`.`orders`.`payments`;

CREATE COLLECTION `ecommerce`.`users`.`users`;
CREATE COLLECTION `ecommerce`.`users`.`addresses`;
CREATE COLLECTION `ecommerce`.`users`.`preferences`;

CREATE COLLECTION `ecommerce`.`analytics`.`page_views`;
CREATE COLLECTION `ecommerce`.`analytics`.`search_logs`;
CREATE COLLECTION `ecommerce`.`analytics`.`recommendations`;

6.2 多环境隔离 #

text 
app-bucket
├── development Scope
│   ├── users
│   ├── products
│   └── orders
├── staging Scope
│   ├── users
│   ├── products
│   └── orders
└── production Scope
    ├── users
    ├── products
    └── orders

查询不同环境数据：

sql 
SELECT * FROM `app`.`development`.`users`;
SELECT * FROM `app`.`staging`.`users`;
SELECT * FROM `app`.`production`.`users`;

6.3 多租户架构 #

text 
saas-bucket
├── tenant_001 Scope
│   ├── users
│   ├── products
│   └── orders
├── tenant_002 Scope
│   ├── users
│   ├── products
│   └── orders
└── tenant_003 Scope
    ├── users
    ├── products
    └── orders

七、权限控制 #

7.1 角色类型 #

角色 权限范围
bucket_admin 整个Bucket的管理权限
scope_admin 指定Scope的管理权限
collection_admin 指定Collection的管理权限

7.2 创建Scope级别用户 #

bash 
/opt/couchbase/bin/couchbase-cli user-manage \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --set \
    --rbac-username scope_user \
    --rbac-password password123 \
    --rbac-name "Scope User" \
    --roles scope_admin[my-bucket:my-scope] \
    --auth-domain local

7.3 创建Collection级别用户 #

bash 
/opt/couchbase/bin/couchbase-cli user-manage \
    --cluster localhost:8091 \
    --username Administrator \
    --password your-password \
    --set \
    --rbac-username collection_user \
    --rbac-password password123 \
    --rbac-name "Collection User" \
    --roles collection_admin[my-bucket:my-scope:my-collection] \
    --auth-domain local

八、索引与Collection #

8.1 为Collection创建索引 #

sql 
CREATE INDEX idx_users_email 
ON `my-bucket`.`my-scope`.`users`(email);

CREATE INDEX idx_users_name 
ON `my-bucket`.`my-scope`.`users`(name);

8.2 查看Collection索引 #

sql 
SELECT * FROM system:indexes
WHERE keyspace_id = 'users'
AND bucket_id = 'my-bucket'
AND scope_id = 'my-scope';

8.3 建立索引服务 #

sql 
CREATE PRIMARY INDEX ON `my-bucket`.`my-scope`.`users`;

CREATE INDEX idx_products_category 
ON `ecommerce`.`catalog`.`products`(category)
WHERE type = 'product';

九、SDK操作示例 #

9.1 Python SDK #

python 
from couchbase.cluster import Cluster, ClusterOptions
from couchbase.auth import PasswordAuthenticator
from couchbase.options import GetOptions, UpsertOptions

cluster = Cluster(
    'couchbase://localhost',
    ClusterOptions(PasswordAuthenticator('Administrator', 'password'))
)

bucket = cluster.bucket('my-bucket')
scope = bucket.scope('my-scope')
collection = scope.collection('users')

doc = {
    'type': 'user',
    'name': '张三',
    'email': 'zhangsan@example.com',
    'age': 28
}

collection.upsert('user::001', doc)

result = collection.get('user::001')
print(result.content)

query = 'SELECT * FROM `users` WHERE type = $type'
rows = cluster.query(query, QueryOptions(
    query_context='my-bucket.my-scope',
    named_parameters={'type': 'user'}
))
for row in rows:
    print(row)

9.2 Node.js SDK #

javascript 
const couchbase = require('couchbase');

const cluster = new couchbase.Cluster('couchbase://localhost', {
    username: 'Administrator',
    password: 'password'
});

const bucket = cluster.bucket('my-bucket');
const scope = bucket.scope('my-scope');
const collection = scope.collection('users');

const doc = {
    type: 'user',
    name: '张三',
    email: 'zhangsan@example.com',
    age: 28
};

await collection.upsert('user::001', doc);

const result = await collection.get('user::001');
console.log(result.content);

const query = 'SELECT * FROM `users` WHERE type = $1';
const options = {
    parameters: ['user'],
    queryContext: 'my-bucket.my-scope'
};
const { rows } = await cluster.query(query, options);
console.log(rows);

9.3 Java SDK #

java 
import com.couchbase.client.java.*;
import com.couchbase.client.java.query.*;

Cluster cluster = Cluster.connect(
    "localhost",
    ClusterOptions.clusterOptions("Administrator", "password")
);

Bucket bucket = cluster.bucket("my-bucket");
Scope scope = bucket.scope("my-scope");
Collection collection = scope.collection("users");

JsonObject doc = JsonObject.create()
    .put("type", "user")
    .put("name", "张三")
    .put("email", "zhangsan@example.com")
    .put("age", 28);

collection.upsert("user::001", doc);

GetResult result = collection.get("user::001");
System.out.println(result.contentAsObject());

String query = "SELECT * FROM `users` WHERE type = $type";
QueryResult queryResult = cluster.query(query,
    QueryOptions.queryOptions()
        .queryContext("my-bucket.my-scope")
        .parameters(JsonObject.create().put("type", "user"))
);
queryResult.rowsAsObject().forEach(System.out::println);

十、最佳实践 #

10.1 命名规范 #

text 
Scope命名：
- 使用小写字母
- 使用下划线分隔
- 语义化命名

示例：
user_management
order_processing
analytics_reporting

Collection命名：
- 使用复数形式
- 使用小写字母
- 使用下划线分隔

示例：
users
products
order_items

10.2 组织策略 #

text 
按业务领域组织：
├── customer Scope
│   ├── profiles
│   ├── preferences
│   └── activities
├── inventory Scope
│   ├── products
│   ├── categories
│   └── suppliers
└── transaction Scope
    ├── orders
    ├── payments
    └── shipments

按环境组织：
├── dev Scope
├── test Scope
└── prod Scope

10.3 迁移建议 #

从旧版本迁移到Scope/Collection：

sql 
CREATE SCOPE `my-bucket`.`app`;
CREATE COLLECTION `my-bucket`.`app`.`users`;
CREATE COLLECTION `my-bucket`.`app`.`products`;

INSERT INTO `my-bucket`.`app`.`users` (KEY, VALUE)
SELECT META().id, _default
FROM `my-bucket`.`_default`.`_default`
WHERE type = 'user';

十一、总结 #

Scope和Collection要点：

概念 说明 类比
Scope 逻辑分组 Schema
Collection 文档容器 Table
Document 数据记录 Row

最佳实践：

  1. 按业务领域组织Scope
  2. 使用语义化的Collection命名
  3. 合理设置查询上下文
  4. 为每个Collection创建适当的索引
  5. 使用权限控制保护数据

下一步，让我们学习文档插入操作！

最后更新：2026-03-27