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

最佳实践:

  1. 保持类型一致性
  2. 使用有意义的字段名
  3. 合理处理NULL和MISSING
  4. 使用ISO 8601格式存储日期
  5. 避免过度嵌套

下一步,让我们学习Bucket操作!

最后更新:2026-03-27