Couchbase数据类型 #
一、概述 #
Couchbase使用JSON作为文档存储格式,支持JSON规范中的所有数据类型,并扩展了一些特殊类型。
1.1 数据类型分类 #
text
基本类型
├── 数值类型
│ ├── 整数 (INTEGER)
│ └── 浮点数 (FLOAT/DOUBLE)
├── 字符串 (STRING)
├── 布尔值 (BOOLEAN)
└── 空值 (NULL)
复合类型
├── 对象 (OBJECT)
└── 数组 (ARRAY)
特殊类型
├── 缺失 (MISSING)
└── 二进制 (BINARY)
二、基本数据类型 #
2.1 数值类型 #
整数 (INTEGER)
json
{
"age": 25,
"quantity": -100,
"big_number": 9007199254740992
}
N1QL数值范围:
| 类型 | 范围 |
|---|---|
| INTEGER | -2^53 到 2^53 |
| DOUBLE | IEEE 754双精度浮点数 |
浮点数 (FLOAT/DOUBLE)
json
{
"price": 99.99,
"rate": 0.123456789,
"scientific": 1.5e10
}
数值操作:
sql
SELECT
42 AS integer_value,
3.14 AS float_value,
1.5e10 AS scientific_notation,
-100 AS negative_value;
2.2 字符串类型 (STRING) #
json
{
"name": "张三",
"email": "zhangsan@example.com",
"description": "这是一个包含\"引号\"的字符串",
"unicode": "你好世界 🌍"
}
字符串特性:
| 特性 | 说明 |
|---|---|
| 编码 | UTF-8 |
| 引号 | 双引号 |
| 转义 | ", \, /, \b, \f, \n, \r, \t, \uXXXX |
字符串操作:
sql
SELECT
"Hello World" AS simple_string,
"Line1\nLine2" AS multiline,
"Unicode: 你好" AS unicode_string,
"Quote: \"test\"" AS escaped;
2.3 布尔类型 (BOOLEAN) #
json
{
"is_active": true,
"is_deleted": false,
"has_permission": true
}
布尔操作:
sql
SELECT
true AS yes,
false AS no,
NOT true AS not_true,
true AND false AS and_result,
true OR false AS or_result;
2.4 空值 (NULL) #
json
{
"middle_name": null,
"phone": null
}
NULL与MISSING区别:
sql
SELECT
a IS NULL AS is_null,
a IS MISSING AS is_missing
FROM [
{"a": null},
{"b": 1}
] AS t;
结果:
| a | is_null | is_missing |
|---|---|---|
| null | true | false |
| - | false | true |
三、复合数据类型 #
3.1 对象类型 (OBJECT) #
json
{
"user": {
"id": "001",
"name": "张三",
"contact": {
"email": "zhangsan@example.com",
"phone": "13800138000"
},
"address": {
"city": "北京",
"street": "朝阳路100号",
"zipcode": "100020"
}
}
}
对象操作:
sql
SELECT
user.name,
user.contact.email,
user.address.city
FROM `my-bucket`.`_default`.`_default`
WHERE type = 'user';
SELECT
OBJECT_NAMES(user) AS field_names,
OBJECT_VALUES(user) AS field_values,
OBJECT_LENGTH(user) AS field_count
FROM `my-bucket`.`_default`.`_default`
WHERE type = 'user';
3.2 数组类型 (ARRAY) #
json
{
"hobbies": ["阅读", "游泳", "编程"],
"scores": [95, 88, 92, 85],
"mixed": [1, "two", true, null, {"key": "value"}],
"nested": [[1, 2], [3, 4], [5, 6]]
}
数组操作:
sql
SELECT
hobbies[0] AS first_hobby,
hobbies[-1] AS last_hobby,
ARRAY_LENGTH(hobbies) AS count,
ARRAY_APPEND(hobbies, "游戏") AS with_new_item
FROM `my-bucket`.`_default`.`_default`
WHERE type = 'user';
常用数组函数:
| 函数 | 说明 | 示例 |
|---|---|---|
| ARRAY_LENGTH | 数组长度 | ARRAY_LENGTH([1,2,3]) = 3 |
| ARRAY_APPEND | 追加元素 | ARRAY_APPEND([1,2], 3) = [1,2,3] |
| ARRAY_PREPEND | 前置元素 | ARRAY_PREPEND([2,3], 1) = [1,2,3] |
| ARRAY_CONCAT | 连接数组 | ARRAY_CONCAT([1], [2,3]) = [1,2,3] |
| ARRAY_CONTAINS | 是否包含 | ARRAY_CONTAINS([1,2,3], 2) = true |
| ARRAY_FIRST | 第一个元素 | ARRAY_FIRST([1,2,3]) = 1 |
| ARRAY_LAST | 最后一个元素 | ARRAY_LAST([1,2,3]) = 3 |
四、特殊类型 #
4.1 MISSING类型 #
MISSING表示字段不存在,与NULL不同:
sql
SELECT
name,
age,
age IS NULL AS is_null,
age IS MISSING AS is_missing
FROM `my-bucket`.`_default`.`_default`;
处理MISSING:
sql
SELECT
name,
IFMISSING(phone, 'N/A') AS phone,
IFMISSINGORNULL(email, 'unknown@example.com') AS email
FROM `my-bucket`.`_default`.`_default`;
4.2 二进制类型 #
Couchbase支持存储二进制数据:
json
{
"type": "binary",
"data": "SGVsbG8gV29ybGQh",
"encoding": "base64"
}
五、类型判断函数 #
5.1 TYPE函数 #
sql
SELECT
TYPE(42) AS num_type,
TYPE("hello") AS str_type,
TYPE(true) AS bool_type,
TYPE(null) AS null_type,
TYPE([1,2,3]) AS arr_type,
TYPE({"a":1}) AS obj_type;
返回值:
| 类型 | 返回值 |
|---|---|
| 整数 | “number” |
| 浮点数 | “number” |
| 字符串 | “string” |
| 布尔值 | “boolean” |
| NULL | “null” |
| 数组 | “array” |
| 对象 | “object” |
| MISSING | “missing” |
5.2 类型检查函数 #
sql
SELECT
IS_NUMBER(age) AS is_num,
IS_STRING(name) AS is_str,
IS_BOOLEAN(active) AS is_bool,
IS_ARRAY(hobbies) AS is_arr,
IS_OBJECT(address) AS is_obj
FROM `my-bucket`.`_default`.`_default`;
类型检查函数列表:
| 函数 | 说明 |
|---|---|
| IS_NUMBER(v) | 是否为数值 |
| IS_STRING(v) | 是否为字符串 |
| IS_BOOLEAN(v) | 是否为布尔值 |
| IS_ARRAY(v) | 是否为数组 |
| IS_OBJECT(v) | 是否为对象 |
| IS_NULL(v) | 是否为NULL |
| IS_MISSING(v) | 是否为MISSING |
六、类型转换 #
6.1 TO_STRING #
sql
SELECT
TO_STRING(42) AS str_num,
TO_STRING(3.14) AS str_float,
TO_STRING(true) AS str_bool;
6.2 TO_NUMBER #
sql
SELECT
TO_NUMBER("42") AS num_str,
TO_NUMBER("3.14") AS float_str,
TO_NUMBER(true) AS num_bool;
6.3 TO_BOOLEAN #
sql
SELECT
TO_BOOLEAN(1) AS bool_num,
TO_BOOLEAN("true") AS bool_str,
TO_BOOLEAN(0) AS bool_zero;
6.4 TO_ARRAY #
sql
SELECT
TO_ARRAY(1) AS arr_num,
TO_ARRAY("hello") AS arr_str,
TO_ARRAY([1,2,3]) AS arr_arr;
6.5 TO_OBJECT #
sql
SELECT
TO_OBJECT({"a": 1}) AS obj_obj,
TO_OBJECT([{"a": 1}, {"b": 2}]) AS obj_arr;
七、日期时间类型 #
7.1 日期时间存储 #
json
{
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T18:45:30+08:00",
"birth_date": "1990-05-20"
}
7.2 日期函数 #
sql
SELECT
DATE_FORMAT_STR(created_at, 'YYYY-MM-DD') AS date_only,
DATE_PART(created_at, 'year') AS year,
DATE_PART(created_at, 'month') AS month,
DATE_PART(created_at, 'day') AS day,
DATE_PART(created_at, 'hour') AS hour,
DATE_DIFF(created_at, updated_at, 'day') AS days_diff
FROM `my-bucket`.`_default`.`_default`;
常用日期函数:
| 函数 | 说明 |
|---|---|
| CLOCK_STR() | 当前时间字符串 |
| DATE_PART(date, part) | 提取日期部分 |
| DATE_FORMAT_STR(date, fmt) | 格式化日期 |
| DATE_DIFF(d1, d2, part) | 日期差值 |
| DATE_ADD_STR(date, n, part) | 日期加减 |
| NOW_STR() | 当前UTC时间 |
7.3 日期构造 #
sql
SELECT
DATE_ADD_STR("2024-01-15", 7, "day") AS week_later,
DATE_ADD_STR("2024-01-15", -1, "month") AS month_ago,
DATE_TRUNC_STR("2024-01-15T10:30:00Z", "day") AS truncated;
八、实际应用示例 #
8.1 用户文档 #
json
{
"type": "user",
"id": "user_001",
"name": "张三",
"age": 28,
"email": "zhangsan@example.com",
"is_active": true,
"score": 95.5,
"hobbies": ["阅读", "游泳", "编程"],
"address": {
"city": "北京",
"street": "朝阳路100号",
"zipcode": "100020"
},
"metadata": {
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T15:45:00Z",
"version": 1
},
"tags": ["vip", "premium"],
"settings": null
}
8.2 产品文档 #
json
{
"type": "product",
"id": "prod_001",
"name": "iPhone 15",
"price": 7999.00,
"stock": 100,
"is_available": true,
"categories": ["电子产品", "手机", "苹果"],
"specs": {
"color": ["黑色", "白色", "蓝色"],
"storage": [128, 256, 512],
"weight": 171.5
},
"ratings": [5, 4, 5, 4, 5],
"created_at": "2024-01-01T00:00:00Z"
}
8.3 订单文档 #
json
{
"type": "order",
"id": "order_001",
"user_id": "user_001",
"items": [
{
"product_id": "prod_001",
"name": "iPhone 15",
"quantity": 1,
"price": 7999.00
},
{
"product_id": "prod_002",
"name": "手机壳",
"quantity": 2,
"price": 99.00
}
],
"total_amount": 8197.00,
"status": "pending",
"payment": {
"method": "credit_card",
"transaction_id": "txn_123456"
},
"created_at": "2024-01-15T10:30:00Z"
}
九、类型设计最佳实践 #
9.1 字段类型选择 #
| 场景 | 推荐类型 | 说明 |
|---|---|---|
| 标识符 | 字符串 | 便于生成唯一ID |
| 数量/计数 | 整数 | 避免精度问题 |
| 金额 | 浮点数或字符串 | 注意精度处理 |
| 状态 | 字符串或整数 | 便于理解和扩展 |
| 时间 | ISO 8601字符串 | 标准格式 |
| 标签 | 数组 | 便于搜索 |
| 配置 | 对象 | 结构化存储 |
9.2 类型一致性 #
json
{
"good_example": {
"age": 25,
"price": 99.99,
"is_active": true,
"tags": ["tag1", "tag2"]
},
"bad_example": {
"age": "25",
"price": "99.99",
"is_active": "true",
"tags": "tag1,tag2"
}
}
9.3 处理可选字段 #
sql
SELECT
name,
IFMISSING(middle_name, '') AS middle_name,
IFMISSINGORNULL(phone, 'N/A') AS phone,
IFMISSING(age, 0) AS age
FROM `my-bucket`.`_default`.`_default`;
十、总结 #
数据类型要点:
| 类型 | 用途 | 示例 |
|---|---|---|
| NUMBER | 数值计算 | age, price, quantity |
| STRING | 文本数据 | name, email, description |
| BOOLEAN | 状态标记 | is_active, has_permission |
| NULL | 空值表示 | middle_name: null |
| ARRAY | 列表数据 | hobbies, tags, items |
| OBJECT | 嵌套结构 | address, metadata |
最佳实践:
- 保持类型一致性
- 使用有意义的字段名
- 合理处理NULL和MISSING
- 使用ISO 8601格式存储日期
- 避免过度嵌套
下一步,让我们学习Bucket操作!
最后更新:2026-03-27