DataStoreKeyInfo

概览

字段	值
Kind	Data · 数据 Data
Realm	server

DataStoreKeyInfo 是 DataStore 读写操作返回的键信息对象，包含创建/更新时间、版本号、scope、key、元数据、用户 ID 和删除状态。

适用场景

启用 WithKeyInfo 后，在 GetAsync、SetAsync、IncrementAsync、RemoveAsync、UpdateAsync 等操作中读取版本号、元数据或用户 ID，用于审计、展示或乐观锁处理。

使用要点

在对应 options 中设置 WithKeyInfo=true 后，从 DataStore 方法的额外返回值获得 DataStoreKeyInfo；读取属性或调用 GetMetaDatas/GetUserIds 获取写入时附加的信息。

注意事项

该类型不可构造，禁止使用 DataStoreKeyInfo.New() 或直接以类型名调用创建实例；键信息仅随 DataStore 方法调用返回，若未接收第二个返回值则无法取得。CreatedTime 与 UpdatedTime 以毫秒时间戳表示，Metas 与 UserIds 需通过属性或对应方法读取，不要假设其一定非空。

代码示例

通过 GetAsync 获取 KeyInfo

-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local dataStore = DataStoreService:GetDataStore('PlayerData', 'global')

Task:Spawn(function()
    local options = DataStoreGetOptions.New()
    options.WithKeyInfo = true
    local value, keyInfo = dataStore:GetAsync('player_001', options)
    if keyInfo ~= nil then
        print('版本:', keyInfo.Version, 'scope:', keyInfo.Scope, 'key:', keyInfo.Key)
        print('元数据:', keyInfo:GetMetaDatas())
        print('用户 ID:', keyInfo:GetUserIds())
    end
end)

属性 (8)

Name	类型	默认值	说明
CreatedTime	Int	0	键值记录的创建时间，标题标注为毫秒时间戳，类型为 Int。它属于 DataStoreKeyInfo，用于描述对应键在数据存储中建立记录的时间信息。
UpdatedTime	Int	0	键值记录的更新时间，标题标注为毫秒时间戳，类型为 Int。它由 DataStoreKeyInfo 携带，用于描述该键最近一次写入的时间信息。
Version	String	""	该记录的版本号，类型为 String。它由 DataStoreKeyInfo 携带，用于标识当前键值信息对应的版本。
Scope	String	""	该记录所属的前置域（Scope），类型为 String。它由 DataStoreKeyInfo 携带，用于标明键值信息所在的作用域。
Key	String	""	该记录对应的键名，类型为 String。它由 DataStoreKeyInfo 携带，标识当前键值信息所描述的键。
Metas	Table	{}	用户自定义元数据，类型为 Table。它由 DataStoreKeyInfo 携带，用于存放写入时通过设置选项附加的元数据表。
UserIds	Table	[]	关联的用户 ID 列表，类型为 Table。它由 DataStoreKeyInfo 携带，保存写入时通过设置选项登记的用户标识集合。
IsDeleted	Bool	false	表示当前键值记录是否已被删除，类型为 Bool。它由 DataStoreKeyInfo 携带，用于反映该键的删除状态。

函数 (2)

GetMetaDatas

签名：GetMetaDatas() -> Table (元数据)

获取该键的元数据字典。

返回值 Table (元数据)

示例代码

读取 KeyInfo 元数据

-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local dataStore = DataStoreService:GetDataStore('PlayerData', 'global')

Task:Spawn(function()
    local options = DataStoreGetOptions.New()
    options.WithKeyInfo = true
    local _, keyInfo = dataStore:GetAsync('player_001', options)
    local metas = keyInfo and keyInfo:GetMetaDatas() or {}
    print(metas.source)
end)

GetUserIds

签名：GetUserIds() -> Table (用户ID列表)

获取与该键关联的用户 ID 列表。

返回值 Table (用户ID列表)

示例代码

读取 KeyInfo 用户 ID

-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local dataStore = DataStoreService:GetDataStore('PlayerData', 'global')

Task:Spawn(function()
    local options = DataStoreGetOptions.New()
    options.WithKeyInfo = true
    local _, keyInfo = dataStore:GetAsync('player_001', options)
    for _, userId in ipairs((keyInfo and keyInfo:GetUserIds()) or {}) do
        print(userId)
    end
end)