HarmonyOSAPI:@ohos.data.distributedData (分布式数据管理)
版本:v3.1 Beta
@ohos.data.distributedData (分布式数据管理)
更新时间: 2023-03-17 18:27
分布式数据管理为应用程序提供不同设备间数据库的分布式协同能力。通过调用分布式数据各个接口,应用程序可将数据保存到分布式数据库中,并可对分布式数据库中的数据进行增加、删除、修改、查询、同步等操作。
该模块提供以下分布式数据管理相关的常用功能:
- KVManager:数据管理实例,用于获取KVStore的相关信息。
- KvStoreResultSet8+:提供获取KVStore数据库结果集的相关方法,包括查询和移动数据读取位置等。
- Query8+:使用谓词表示数据库查询,提供创建Query实例、查询数据库中的数据和添加谓词的方法。
- KVStore:KVStore数据库实例,提供增加数据、删除数据和订阅数据变更、订阅数据同步完成的方法。
- SingleKVStore:单版本分布式数据库,继承自KVStore,不对数据所属设备进行区分,提供查询数据和同步数据的方法。
- DeviceKVStore8+:设备协同数据库,继承自KVStore,以设备维度对数据进行区分,提供查询数据和同步数据的方法。
说明
本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
导入模块
import distributedData from '@ohos.data.distributedData';
distributedData.createKVManager
createKVManager(config: KVManagerConfig, callback: AsyncCallback<KVManager>): void
创建一个KVManager对象实例,用于管理数据库对象,使用callback异步回调。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
config | 是 | 提供KVManager实例的配置信息,包括调用方的包名和用户信息。 | |
callback | AsyncCallback<KVManager> | 是 | 回调函数。返回创建的KVManager对象实例。 |
示例:
let kvManager;
try {
const kvManagerConfig = {
bundleName : 'com.example.datamanagertest',
userInfo : {
userId : '0',
userType : distributedData.UserType.SAME_USER_ID
}
}
distributedData.createKVManager(kvManagerConfig, function (err, manager) {
if (err) {
console.log("Failed to create KVManager: " + JSON.stringify(err));
return;
}
console.log("Succeeded in creating KVManager");
kvManager = manager;
});
} catch (e) {
console.log("An unexpected error occurred. Error:" + e);
}
distributedData.createKVManager
createKVManager(config: KVManagerConfig): Promise<KVManager>
创建一个KVManager对象实例,用于管理数据库对象,使用Promise异步回调。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
config | 是 | 提供KVManager实例的配置信息,包括调用方的包名和用户信息。 |
返回值:
类型 | 说明 |
Promise<KVManager> | Promise对象。返回创建的KVManager对象实例。 |
示例:
let kvManager;
try {
const kvManagerConfig = {
bundleName : 'com.example.datamanagertest',
userInfo : {
userId : '0',
userType : distributedData.UserType.SAME_USER_ID
}
}
distributedData.createKVManager(kvManagerConfig).then((manager) => {
console.log("createKVManager success");
kvManager = manager;
}).catch((err) => {
console.log("createKVManager err: " + JSON.stringify(err));
});
} catch (e) {
console.log("An unexpected error occurred. Error:" + e);
}
KVManagerConfig
提供KVManager实例的配置信息,包括调用方的包名和用户信息。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
名称 | 类型 | 必填 | 说明 |
userInfo | 是 | 调用方的用户信息。 | |
bundleName | string | 是 | 调用方的包名。 |
UserInfo
用户信息。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
名称 | 类型 | 必填 | 说明 |
userId | string | 否 | 指示要设置的用户ID。 |
userType | 否 | 指示要设置的用户类型。 |
UserType
用户类型枚举。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
名称 | 值 | 说明 |
SAME_USER_ID | 0 | 使用同一帐户登录不同设备的用户。 |
KVManager
数据管理实例,用于获取KVStore的相关信息。在调用KVManager的方法前,需要先通过createKVManager构建一个KVManager实例。
getKVStore
getKVStore<T extends KVStore>(storeId: string, options: Options, callback: AsyncCallback<T>): void
通过指定Options和storeId,创建并获取KVStore数据库,使用callback异步回调。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
storeId | string | 是 | 数据库唯一标识符,长度不大于MAX_STORE_ID_LENGTH。 |
options | 是 | 创建KVStore实例的配置信息。 | |
callback | AsyncCallback<T> | 是 | 回调函数。返回创建的KVStore数据库实例。 |
示例:
let kvStore;
let kvManager;
try {
const options = {
createIfMissing : true,
encrypt : false,
backup : false,
autoSync : true,
kvStoreType : distributedData.KVStoreType.SINGLE_VERSION,
securityLevel : distributedData.SecurityLevel.S2,
};
kvManager.getKVStore('storeId', options, function (err, store) {
if (err) {
console.log("getKVStore err: " + JSON.stringify(err));
return;
}
console.log("getKVStore success");
kvStore = store;
});
} catch (e) {
console.log("An unexpected error occurred. Error:" + e);
}
getKVStore
getKVStore<T extends KVStore>(storeId: string, options: Options): Promise<T>
通过指定Options和storeId,创建并获取KVStore数据库,使用Promise异步回调。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
storeId | string | 是 | 数据库唯一标识符,长度不大于MAX_STORE_ID_LENGTH。 |
options | 是 | 创建KVStore实例的配置信息。 |
返回值:
类型 | 说明 |
Promise<T> ,<T extends KVStore> | Promise对象。返回创建的KVStore数据库实例。 |
示例:
let kvStore;
let kvManager;
try {
const options = {
createIfMissing : true,
encrypt : false,
backup : false,
autoSync : true,
kvStoreType : distributedData.KVStoreType.SINGLE_VERSION,
securityLevel : distributedData.SecurityLevel.S2,
};
kvManager.getKVStore('storeId', options).then((store) => {
console.log("getKVStore success");
kvStore = store;
}).catch((err) => {
console.log("getKVStore err: " + JSON.stringify(err));
});
} catch (e) {
console.log("An unexpected error occurred. Error:" + e);
}
closeKVStore8+
closeKVStore(appId: string, storeId: string, kvStore: KVStore, callback: AsyncCallback<void>): void
通过storeId的值关闭指定的KVStore数据库,使用callback异步回调。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
appId | string | 是 | 所调用数据库方的包名。 |
storeId | string | 是 | 要关闭的数据库唯一标识符,长度不大于MAX_STORE_ID_LENGTH。 |
kvStore | 是 | 要关闭的KVStore数据库。 | |
callback | AsyncCallback<void> | 是 | 回调函数。 |
示例:
let kvStore;
let kvManager;
const options = {
createIfMissing: true,
encrypt: false,
backup: false,
autoSync: true,
kvStoreType: distributedData.KVStoreType.SINGLE_VERSION,
schema: '',
securityLevel: distributedData.SecurityLevel.S2,
}
try {
kvManager.getKVStore('storeId', options, async function (err, store) {
console.log('getKVStore success');
kvStore = store;
kvManager.closeKVStore('appId', 'storeId', kvStore, function (err, data) {
console.log('closeKVStore success');
});
});
} catch (e) {
console.log('closeKVStore e ' + e);
}
closeKVStore8+
closeKVStore(appId: string, storeId: string, kvStore: KVStore): Promise<void>
通过storeId的值关闭指定的KVStore数据库,使用Promise异步回调。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
appId | string | 是 | 所调用数据库方的包名。 |
storeId | string | 是 | 要关闭的数据库唯一标识符,长度不大于MAX_STORE_ID_LENGTH。 |
kvStore | 是 | 要关闭的KVStore数据库。 |
返回值:
类型 | 说明 |
Promise<void> | 无返回结果的Promise对象。 |
示例:
let kvManager;
let kvStore;
const options = {
createIfMissing: true,
encrypt: false,
backup: false,
autoSync: true,
kvStoreType: distributedData.KVStoreType.SINGLE_VERSION,
schema: '',
securityLevel: distributedData.SecurityLevel.S2,
}
try {
kvManager.getKVStore('storeId', options).then(async (store) => {
console.log('getKVStore success');
kvStore = store;
kvManager.closeKVStore('appId', 'storeId', kvStore).then(() => {
console.log('closeKVStore success');
}).catch((err) => {
console.log('closeKVStore err ' + JSON.stringify(err));
});
}).catch((err) => {
console.log('CloseKVStore getKVStore err ' + JSON.stringify(err));
});
} catch (e) {
console.log('closeKVStore e ' + e);
}
deleteKVStore8+
deleteKVStore(appId: string, storeId: string, callback: AsyncCallback<void>): void
通过storeId的值删除指定的KVStore数据库,使用callback异步回调。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
appId | string | 是 | 所调用数据库方的包名。 |
storeId | string | 是 | 要删除的数据库唯一标识符,长度不大于MAX_STORE_ID_LENGTH。 |
callback | AsyncCallback<void> | 是 | 回调函数。 |
示例:
let kvManager;
let kvStore;
const options = {
createIfMissing : true,
encrypt : false,
backup : false,
autoSync : true,
kvStoreType : distributedData.KVStoreType.SINGLE_VERSION,
schema : '',
securityLevel : distributedData.SecurityLevel.S2,
}
try {
kvManager.getKVStore('store', options, async function (err, store) {
console.log('getKVStore success');
kvStore = store;
kvManager.deleteKVStore('appId', 'storeId', function (err, data) {
console.log('deleteKVStore success');
});
});
} catch (e) {
console.log('DeleteKVStore e ' + e);
}
deleteKVStore8+
deleteKVStore(appId: string, storeId: string): Promise<void>
通过storeId的值删除指定的KVStore数据库,使用Promise异步回调。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
appId | string | 是 | 所调用数据库方的包名。 |
storeId | string | 是 | 要删除的数据库唯一标识符,长度不大于MAX_STORE_ID_LENGTH。 |
返回值:
类型 | 说明 |
Promise<void> | 无返回结果的Promise对象。 |
示例:
let kvManager;
let kvStore;
const options = {
createIfMissing : true,
encrypt : false,
backup : false,
autoSync : true,
kvStoreType : distributedData.KVStoreType.SINGLE_VERSION,
schema : '',
securityLevel : distributedData.SecurityLevel.S2,
}
try {
kvManager.getKVStore('storeId', options).then(async (store) => {
console.log('getKVStore success');
kvStore = store;
kvManager.deleteKVStore('appId', 'storeId').then(() => {
console.log('deleteKVStore success');
}).catch((err) => {
console.log('deleteKVStore err ' + JSON.stringify(err));
});
}).catch((err) => {
console.log('getKVStore err ' + JSON.stringify(err));
});
} catch (e) {
console.log('deleteKVStore e ' + e);
}
getAllKVStoreId8+
getAllKVStoreId(appId: string, callback: AsyncCallback<string[]>): void
获取所有通过getKVStore方法创建的且没有调用deleteKVStore方法删除的KVStore数据库的storeId,使用callback异步回调。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
appId | string | 是 | 所调用数据库方的包名。 |
callback | AsyncCallback<string[]> | 是 | 回调函数。返回所有创建的KvStore数据库的storeId。 |
示例:
let kvManager;
try {
kvManager.getAllKVStoreId('appId', function (err, data) {
console.log('GetAllKVStoreId success');
console.log('GetAllKVStoreId size = ' + data.length);
});
} catch (e) {
console.log('GetAllKVStoreId e ' + e);
}
getAllKVStoreId8+
getAllKVStoreId(appId: string): Promise<string[]>
获取所有通过getKVStore方法创建的且没有调用deleteKVStore方法删除的KVStore数据库的storeId,使用Promise异步回调。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
appId | string | 是 | 所调用数据库方的包名。 |
返回值:
类型 | 说明 |
Promise<string[]> | Promise对象。返回所有创建的KvStore数据库的storeId。 |
示例:
let kvManager;
try {
console.log('GetAllKVStoreId');
kvManager.getAllKVStoreId('appId').then((data) => {
console.log('getAllKVStoreId success');
console.log('size = ' + data.length);
}).catch((err) => {
console.log('getAllKVStoreId err ' + JSON.stringify(err));
});
} catch(e) {
console.log('getAllKVStoreId e ' + e);
}
on('distributedDataServiceDie')8+
on(event: 'distributedDataServiceDie', deathCallback: Callback<void>): void
订阅服务状态变更通知。
系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore
参数:
参数名 | 类型 | 必填 | 说明 |
event | string | 是 | 订阅的事件名,固定为'distributedDataServiceDie',即服务状态变更事件。 |
deathCallback | Callback<void> | 是 | 回调函数。 |
示例:
let kvManager;
try {
console.log('KVManagerOn');
const deathCallback = function () {
console.log('death callback call');
}
kvManager.on('distributedDataServiceDie', deathCallback);
} catch (e) {
console.log("An unexpected error occurred. Error:" + e);
}
off('distributedDataServiceDie')8+
off(event: 'distributedDataServiceDie', deathCallback?: Callback<void>): void
取消订阅服务状态变更通知。
系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore
参数:
参数名 | 类型 | 必填 | 说明 |
event | string | 是 | 取消订阅的事件名,固定为'distributedDataServiceDie',即服务状态变更事件。 |
deathCallback | Callback<void> | 否 | 回调函数。 |
示例:
let kvManager;
try {
console.log('KVManagerOff');
const deathCallback = function () {
console.log('death callback call');
}
kvManager.off('distributedDataServiceDie', deathCallback);
} catch (e) {
console.log("An unexpected error occurred. Error:" + e);
}
Options
用于提供创建数据库的配置信息。
名称 | 类型 | 必填 | 说明 |
createIfMissing | boolean | 否 | 当数据库文件不存在时是否创建数据库,默认创建。 系统能力: SystemCapability.DistributedDataManager.KVStore.Core |
encrypt | boolean | 否 | 设置数据库文件是否加密,默认不加密。 系统能力: SystemCapability.DistributedDataManager.KVStore.Core |
backup | boolean | 否 | 设置数据库文件是否备份,默认备份。 系统能力: SystemCapability.DistributedDataManager.KVStore.Core |
autoSync | boolean | 否 | 设置数据库文件是否自动同步,默认不自动同步。 此接口能力在HarmonyOS 3.1Beta1暂不支持。 系统能力: SystemCapability.DistributedDataManager.KVStore.Core 需要权限: ohos.permission.DISTRIBUTED_DATASYNC |
kvStoreType | 否 | 设置要创建的数据库类型,默认为多设备协同数据库。 系统能力: SystemCapability.DistributedDataManager.KVStore.Core | |
securityLevel | 否 | 设置数据库安全级别,默认不设置安全级别。 系统能力: SystemCapability.DistributedDataManager.KVStore.Core | |
schema8+ | Schema | 否 | 设置定义存储在数据库中的值。 系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore |
KVStoreType
KVStore数据库类型枚举。
名称 | 值 | 说明 |
DEVICE_COLLABORATION | 0 | 表示多设备协同数据库。 数据库特点: 数据以设备的维度管理,不存在冲突;支持按照设备的维度查询数据。 系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore |
SINGLE_VERSION | 1 | 表示单版本数据库。 数据库特点: 数据不分设备,设备之间修改相同的key会覆盖。 系统能力: SystemCapability.DistributedDataManager.KVStore.Core |
MULTI_VERSION | 2 | 表示多版本数据库。当前暂不支持使用此接口。 系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore |
SecurityLevel
数据库的安全级别枚举。
名称 | 值 | 说明 |
NO_LEVEL | 0 | 表示数据库不设置安全级别。 系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore |
S0 | 1 | 表示数据库的安全级别为公共级别。 系统能力: SystemCapability.DistributedDataManager.KVStore.Core |
S1 | 2 | 表示数据库的安全级别为低级别,当数据泄露时会产生较低影响。例如,包含壁纸等系统数据的数据库。 系统能力: SystemCapability.DistributedDataManager.KVStore.Core |
S2 | 3 | 表示数据库的安全级别为中级别,当数据泄露时会产生较大影响。例如,包含录音、视频等用户生成数据或通话记录等信息的数据库。 系统能力: SystemCapability.DistributedDataManager.KVStore.Core |
S3 | 5 | 表示数据库的安全级别为高级别,当数据泄露时会产生重大影响。例如,包含用户运动、健康、位置等信息的数据库。 系统能力: SystemCapability.DistributedDataManager.KVStore.Core |
S4 | 6 | 表示数据库的安全级别为关键级别,当数据泄露时会产生严重影响。例如,包含认证凭据、财务数据等信息的数据库。 系统能力: SystemCapability.DistributedDataManager.KVStore.Core |
Constants
KVStore常量。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
名称 | 值 | 说明 |
MAX_KEY_LENGTH | 1024 | 数据库中Key允许的最大长度,单位字节。 |
MAX_VALUE_LENGTH | 4194303 | 数据库中Value允许的最大长度,单位字节。 |
MAX_KEY_LENGTH_DEVICE | 896 | 最大设备密钥长度,单位字节。 |
MAX_STORE_ID_LENGTH | 128 | 数据库标识符允许的最大长度,单位字节。 |
MAX_QUERY_LENGTH | 512000 | 最大查询长度,单位字节。 |
MAX_BATCH_SIZE | 128 | 最大批处理操作数量。 |
Schema8+
表示数据库模式,可以在创建或打开数据库时创建Schema对象并将它们放入Options中。
系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore
名称 | 类型 | 可读 | 可写 | 说明 |
root8+ | 是 | 是 | 表示json根对象。 | |
indexes8+ | Array<string> | 是 | 是 | 表示json类型的字符串数组。 |
mode8+ | number | 是 | 是 | 表示Schema的模式。 |
skip8+ | number | 是 | 是 | Schema的跳跃大小。 |
constructor8+
constructor()
用于创建Schema实例的构造函数。
系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore
FieldNode8+
表示 Schema 实例的节点,提供定义存储在数据库中的值的方法。
系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore
名称 | 类型 | 可读 | 可写 | 说明 |
nullable8+ | boolean | 是 | 是 | 表示数据库字段是否可以为空。 |
default8+ | string | 是 | 是 | 表示Fieldnode的默认值。 |
type8+ | number | 是 | 是 | 表示指定节点对应数据类型的值。 |
constructor8+
constructor(name: string)
用于创建带有string字段FieldNode实例的构造函数。
系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore
参数:
参数名 | 类型 | 必填 | 说明 |
name | string | 是 | FieldNode的值。 |
appendChild8+
appendChild(child: FieldNode): boolean
在当前 FieldNode 中添加一个子节点。
系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore
参数:
参数名 | 类型 | 必填 | 说明 |
child | 是 | 要附加的域节点。 |
返回值:
类型 | 说明 |
boolean | 返回true表示子节点成功添加到FieldNode;返回false则表示操作失败。 |
示例:
import ddm from '@ohos.data.distributedData';
try {
let node = new ddm.FieldNode("root");
let child1 = new ddm.FieldNode("child1");
let child2 = new ddm.FieldNode("child2");
let child3 = new ddm.FieldNode("child3");
node.appendChild(child1);
node.appendChild(child2);
node.appendChild(child3);
console.log("appendNode " + JSON.stringify(node));
child1 = null;
child2 = null;
child3 = null;
node = null;
} catch (e) {
console.log("AppendChild " + e);
}
KvStoreResultSet8+
提供获取KVStore数据库结果集的相关方法,包括查询和移动数据读取位置等。
在调用KvStoreResultSet的方法前,需要先通过getKVStore构建一个KVStore实例。
getCount8+
getCount(): number
获取结果集中的总行数。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
number | 返回数据的总行数。 |
示例:
let kvStore;
try {
let resultSet;
kvStore.getResultSet('batch_test_string_key').then((result) => {
console.log('getResultSet succeed.');
resultSet = result;
}).catch((err) => {
console.log('getResultSet failed: ' + err);
});
const count = resultSet.getCount();
console.log("getCount succeed:" + count);
} catch (e) {
console.log("getCount failed: " + e);
}
getPosition8+
getPosition(): number
获取结果集中当前的读取位置。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
number | 返回当前读取位置。 |
示例:
let kvStore;
try {
let resultSet;
kvStore.getResultSet('batch_test_string_key').then((result) => {
console.log('getResultSet succeeded.');
resultSet = result;
}).catch((err) => {
console.log('getResultSet failed: ' + err);
});
const position = resultSet.getPosition();
console.log("getPosition succeed:" + position);
} catch (e) {
console.log("getPosition failed: " + e);
}
moveToFirst8+
moveToFirst(): boolean
将读取位置移动到第一行。如果结果集为空,则返回false。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
boolean | 返回true表示操作成功;返回false则表示操作失败。 |
示例:
let kvStore;
try {
let resultSet;
kvStore.getResultSet('batch_test_string_key').then((result) => {
console.log('getResultSet succeed.');
resultSet = result;
}).catch((err) => {
console.log('getResultSet failed: ' + err);
});
const moved1 = resultSet.moveToFirst();
console.log("moveToFirst succeed: " + moved1);
} catch (e) {
console.log("moveToFirst failed " + e);
}
moveToLast8+
moveToLast(): boolean
将读取位置移动到最后一行。如果结果集为空,则返回false。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
boolean | 返回true表示操作成功;返回false则表示操作失败。 |
示例:
let kvStore;
try {
let resultSet;
kvStore.getResultSet('batch_test_string_key').then((result) => {
console.log('getResultSet succeed.');
resultSet = result;
}).catch((err) => {
console.log('getResultSet failed: ' + err);
});
const moved2 = resultSet.moveToLast();
console.log("moveToLast succeed:" + moved2);
} catch (e) {
console.log("moveToLast failed: " + e);
}
moveToNext8+
moveToNext(): boolean
将读取位置移动到下一行。如果结果集为空,则返回false。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
boolean | 返回true表示操作成功;返回false则表示操作失败。 |
示例:
let kvStore;
try {
let resultSet;
kvStore.getResultSet('batch_test_string_key').then((result) => {
console.log('getResultSet succeed.');
resultSet = result;
}).catch((err) => {
console.log('getResultSet failed: ' + err);
});
const moved3 = resultSet.moveToNext();
console.log("moveToNext succeed: " + moved3);
} catch (e) {
console.log("moveToNext failed: " + e);
}
moveToPrevious8+
moveToPrevious(): boolean
将读取位置移动到上一行。如果结果集为空,则返回false。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
boolean | 返回true表示操作成功;返回false则表示操作失败。 |
示例:
let kvStore;
try {
let resultSet;
kvStore.getResultSet('batch_test_string_key').then((result) => {
console.log('getResultSet succeed.');
resultSet = result;
}).catch((err) => {
console.log('getResultSet failed: ' + err);
});
const moved4 = resultSet.moveToPrevious();
console.log("moveToPrevious succeed:" + moved4);
} catch (e) {
console.log("moveToPrevious failed: " + e);
}
move8+
move(offset: number): boolean
将读取位置移动到当前位置的相对偏移量。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
offset | number | 是 | 表示与当前位置的相对偏移量,负偏移表示向后移动,正偏移表示向前移动。 |
返回值:
类型 | 说明 |
boolean | 返回true表示操作成功;返回false则表示操作失败。 |
示例:
let kvStore;
try {
let resultSet;
kvStore.getResultSet('batch_test_string_key').then((result) => {
console.log('getResultSet succeed.');
resultSet = result;
}).catch((err) => {
console.log('getResultSet failed: ' + err);
});
const moved5 = resultSet.move(1);
console.log("move succeed:" + moved5);
} catch (e) {
console.log("move failed: " + e);
}
moveToPosition8+
moveToPosition(position: number): boolean
将读取位置从 0 移动到绝对位置。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
position | number | 是 | 表示绝对位置。 |
返回值:
类型 | 说明 |
boolean | 返回true表示操作成功;返回false则表示操作失败。 |
示例:
let kvStore;
try {
let resultSet;
kvStore.getResultSet('batch_test_string_key').then((result) => {
console.log('getResultSet succeed.');
resultSet = result;
}).catch((err) => {
console.log('getResultSet failed: ' + err);
});
const moved6 = resultSet.moveToPosition(1);
console.log("moveToPosition succeed: " + moved6);
} catch (e) {
console.log("moveToPosition failed: " + e);
}
isFirst8+
isFirst(): boolean
检查读取位置是否为第一行。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
boolean | 返回true表示读取位置为第一行;返回false表示读取位置不是第一行。 |
示例:
let kvStore;
try {
let resultSet;
kvStore.getResultSet('batch_test_string_key').then((result) => {
console.log('getResultSet succeed.');
resultSet = result;
}).catch((err) => {
console.log('getResultSet failed: ' + err);
});
const isfirst = resultSet.isFirst();
console.log("Check isFirst succeed:" + isfirst);
} catch (e) {
console.log("Check isFirst failed: " + e);
}
isLast8+
isLast(): boolean
检查读取位置是否为最后一行。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
boolean | 返回true表示读取位置为最后一行;返回false表示读取位置不是最后一行。 |
示例:
let kvStore;
try {
let resultSet;
kvStore.getResultSet('batch_test_string_key').then((result) => {
console.log('getResultSet succeed.');
resultSet = result;
}).catch((err) => {
console.log('getResultSet failed: ' + err);
});
const islast = resultSet.isLast();
console.log("Check isLast succeed: " + islast);
} catch (e) {
console.log("Check isLast failed: " + e);
}
isBeforeFirst8+
isBeforeFirst(): boolean
检查读取位置是否在第一行之前。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
boolean | 返回true表示读取位置在第一行之前;返回false表示读取位置不在第一行之前。 |
示例:
let kvStore;
try {
let resultSet;
kvStore.getResultSet('batch_test_string_key').then((result) => {
console.log('getResultSet succeed.');
resultSet = result;
}).catch((err) => {
console.log('getResultSet failed: ' + err);
});
const isbeforefirst = resultSet.isBeforeFirst();
console.log("Check isBeforeFirst succeed: " + isbeforefirst);
} catch (e) {
console.log("Check isBeforeFirst failed: " + e);
}
isAfterLast8+
isAfterLast(): boolean
检查读取位置是否在最后一行之后。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
boolean | 返回true表示读取位置在最后一行之后;返回false表示读取位置不在最后一行之后。 |
示例:
let kvStore;
try {
let resultSet;
kvStore.getResultSet('batch_test_string_key').then((result) => {
console.log('getResultSet succeed.');
resultSet = result;
}).catch((err) => {
console.log('getResultSet failed: ' + err);
});
const isafterlast = resultSet.isAfterLast();
console.log("Check isAfterLast succeed:" + isafterlast);
} catch (e) {
console.log("Check isAfterLast failed: " + e);
}
getEntry8+
getEntry(): Entry
从当前位置获取对应的键值对。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
Entry | 返回键值对。 |
示例:
let kvStore;
try {
let resultSet;
kvStore.getResultSet('batch_test_string_key').then((result) => {
console.log('getResultSet succeed.');
resultSet = result;
}).catch((err) => {
console.log('getResultSet failed: ' + err);
});
const entry = resultSet.getEntry();
console.log("getEntry succeed:" + JSON.stringify(entry));
} catch (e) {
console.log("getEntry failed: " + e);
}
Query8+
使用谓词表示数据库查询,提供创建Query实例、查询数据库中的数据和添加谓词的方法。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
constructor8+
constructor()
用于创建Schema实例的构造函数。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
reset8+
reset(): Query
重置Query对象。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
Query | 返回重置的Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.equalTo("key", "value");
console.log("query is " + query.getSqlLike());
query.reset();
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("simply calls should be ok :" + e);
}
equalTo8+
equalTo(field: string, value: number|string|boolean): Query
构造一个Query对象来查询具有指定字段的条目,其值等于指定的值。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
value | number|string|boolean | 是 | 表示指定的值。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.equalTo("field", "value");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
notEqualTo8+
notEqualTo(field: string, value: number|string|boolean): Query
构造一个Query对象以查询具有指定字段且值不等于指定值的条目。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
value | number|string|boolean | 是 | 表示指定的值。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.notEqualTo("field", "value");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
greaterThan8+
greaterThan(field: string, value: number|string|boolean): Query
构造一个Query对象以查询具有大于指定值的指定字段的条目。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
value | number|string|boolean | 是 | 表示指定的值。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.greaterThan("field", "value");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
lessThan8+
lessThan(field: string, value: number|string): Query
构造一个Query对象以查询具有小于指定值的指定字段的条目。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
value | number|string | 是 | 表示指定的值。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.lessThan("field", "value");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
greaterThanOrEqualTo8+
greaterThanOrEqualTo(field: string, value: number|string): Query
构造一个Query对象以查询具有指定字段且值大于或等于指定值的条目。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
value | number|string | 是 | 表示指定的值。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.greaterThanOrEqualTo("field", "value");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
lessThanOrEqualTo8+
lessThanOrEqualTo(field: string, value: number|string): Query
构造一个Query对象以查询具有指定字段且值小于或等于指定值的条目。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
value | number|string | 是 | 表示指定的值。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.lessThanOrEqualTo("field", "value");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
isNull8+
isNull(field: string): Query
构造一个Query对象以查询具有值为null的指定字段的条目。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.isNull("field");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
inNumber8+
inNumber(field: string, valueList: number[]): Query
构造一个Query对象以查询具有指定字段的条目,其值在指定的值列表中。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
valueList | number[] | 是 | 表示指定的值列表。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.inNumber("field", [0, 1]);
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
inString8+
inString(field: string, valueList: string[]): Query
构造一个Query对象以查询具有指定字段的条目,其值在指定的字符串值列表中。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
valueList | string[] | 是 | 表示指定的字符串值列表。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.inString("field", ['test1', 'test2']);
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
notInNumber8+
notInNumber(field: string, valueList: number[]): Query
构造一个Query对象以查询具有指定字段的条目,该字段的值不在指定的值列表中。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
valueList | number[] | 是 | 表示指定的值列表。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.notInNumber("field", [0, 1]);
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
notInString8+
notInString(field: string, valueList: string[]): Query
构造一个Query对象以查询具有指定字段且值不在指定字符串值列表中的条目。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
valueList | string[] | 是 | 表示指定的字符串值列表。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.notInString("field", ['test1', 'test2']);
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
like8+
like(field: string, value: string): Query
构造一个Query对象以查询具有与指定字符串值相似的指定字段的条目。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
value | string | 是 | 表示指定的字符串值。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.like("field", "value");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
unlike8+
unlike(field: string, value: string): Query
构造一个Query对象以查询具有与指定字符串值不相似的指定字段的条目。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
value | string | 是 | 表示指定的字符串值。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.unlike("field", "value");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
and8+
and(): Query
构造一个带有与条件的查询对象。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
Query | 返回查询对象。 |
示例:
try {
let query = new distributedData.Query();
query.notEqualTo("field", "value1");
query.and();
query.notEqualTo("field", "value2");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
or8+
or(): Query
构造一个带有或条件的Query对象。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
Query | 返回查询对象。 |
示例:
try {
let query = new distributedData.Query();
query.notEqualTo("field", "value1");
query.or();
query.notEqualTo("field", "value2");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
orderByAsc8+
orderByAsc(field: string): Query
构造一个Query对象,将查询结果按升序排序。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.notEqualTo("field", "value");
query.orderByAsc("field");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
orderByDesc8+
orderByDesc(field: string): Query
构造一个Query对象,将查询结果按降序排序。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.notEqualTo("field", "value");
query.orderByDesc("field");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
limit8+
limit(total: number, offset: number): Query
构造一个Query对象来指定结果的数量和开始位置。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
total | number | 是 | 表示指定的结果数。 |
offset | number | 是 | 表示起始位置。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
let total = 10;
let offset = 1;
try {
let query = new distributedData.Query();
query.notEqualTo("field", "value");
query.limit(total, offset);
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
isNotNull8+
isNotNull(field: string): Query
构造一个Query对象以查询具有值不为null的指定字段的条目。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
fieId | string | 是 | 表示指定字段,不能包含' ^ '。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.isNotNull("field");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
beginGroup8+
beginGroup(): Query
创建一个带有左括号的查询条件组。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.beginGroup();
query.isNotNull("field");
query.endGroup();
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
endGroup8+
endGroup(): Query
创建一个带有右括号的查询条件组。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.beginGroup();
query.isNotNull("field");
query.endGroup();
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
prefixKey8+
prefixKey(prefix: string): Query
创建具有指定键前缀的查询条件。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
prefix | string | 是 | 表示指定的键前缀。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.prefixKey("$.name");
query.prefixKey("0");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
setSuggestIndex8+
setSuggestIndex(index: string): Query
设置一个指定的索引,将优先用于查询。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
index | string | 是 | 指示要设置的索引。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.setSuggestIndex("$.name");
query.setSuggestIndex("0");
console.log("query is " + query.getSqlLike());
query = null;
} catch (e) {
console.log("duplicated calls should be ok :" + e);
}
deviceId8+
deviceId(deviceId:string):Query
添加设备ID作为key的前缀。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
参数:
参数名 | 类型 | 必填 | 说明 |
deviceId | string | 是 | 指示查询的设备ID。 |
返回值:
类型 | 说明 |
Query | 返回Query对象。 |
示例:
try {
let query = new distributedData.Query();
query.deviceId("deviceId");
console.log("query is " + query.getSqlLike());
} catch (e) {
console.log("should be ok on Method Chaining : " + e);
}
getSqlLike8+
getSqlLike():string
获取Query对象的查询语句。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
返回值:
类型 | 说明 |
string | 返回一个字段列中包含对应子串的结果。 |
示例:
try {
let query = new distributedData.Query();
let sql1 = query.getSqlLike();
console.log("GetSqlLike sql=" + sql1);
} catch (e) {
console.log("duplicated calls should be ok : " + e);
}