Skip to main content

Collection Metadata & Permission

Manage collection ownership and access control for a specific collection via collection(name).metadata. These APIs let you inspect current ownership/permission and update the owner (user or group) or the permission policy.

Get Metadata​

Retrieve the current metadata of a collection, including owner, group and permission. Use this before changing ownership or permissions to understand the current state.

Definition​

await zkdb.db(databaseName: string)
          .collection(collectionName: string)
          .metadata.info(): Promise<TCollectionMetadataResponse>;

Parameters​

  • None

Returns​

  • Promise<TCollectionMetadataResponse | null>: Returns comprehensive collection metadata including schema definition, ownership information, permissions, group assignment, and storage statistics. Returns null if the collection doesn't exist. This provides complete administrative information for collection management and access control.
type TCollectionMetadataResponse = {
  collectionName: string;
  schema: any[]; // serialized schema
  sizeOnDisk?: number;
  owner: string;
  permission: number;
  group?: string;
} | null;

Example​

import { ZkDatabase } from 'zkdb';

const zkdb = await ZkDatabase.connect({
  userName: "chiro-user",
  privateKey: "EKFTciRxyxshZjimay9sktsn7v5PvmC5zPq7q4JnitHUytxUVnFP",
  environment: "node",
  // This URL is for test environment
  url: "https://api.zkdatabase.org/graphql",
});

await zkdb.auth.signIn();

const dbTest = zkdb.db('zkdb_test');
const meta = await dbTest.collection('Shirt').metadata.info();
console.log(meta);

await zkdb.auth.signOut();

Result:​

{
  "collectionName": "Shirt",
  "schema": [
    { "name": "name", "kind": "CircuitString" },
    { "name": "price", "kind": "UInt64" }
  ],
  "sizeOnDisk": 8192,
  "owner": "chiro-user",
  "permission": 983296,
  "group": "admin"
}

Set Owner (User)​

Transfer ownership of the collection to a specific user. After a successful change, the new user becomes the owner with corresponding privileges.

Definition​

await zkdb.db(databaseName: string)
          .collection(collectionName: string)
          .metadata.ownerSet(userName: string): Promise<boolean>;

Parameters​

  • userName (String): New owner user name.

Returns​

  • Promise<boolean>: Returns true when ownership is successfully transferred to the specified user. The new owner gains full administrative control over the collection, including the ability to modify permissions, schema, and transfer ownership again.

Set Owner (Group)​

Transfer ownership of the collection to a group. This is useful when you want to administer access through group-based policies rather than individual users.

Definition​

await zkdb.db(databaseName: string)
          .collection(collectionName: string)
          .metadata.groupSet(groupName: string): Promise<boolean>;

Parameters​

  • groupName (String): New owner group name.

Returns​

  • Promise<boolean>: Returns true when ownership is successfully transferred to the specified group. All members of the group gain administrative control over the collection, including the ability to modify permissions and manage access.

Set Permission​

Update the collection permission policy. Combine this with owner/group changes to enforce who can read or write to the collection.

Definition​

await zkdb.db(databaseName: string)
          .collection(collectionName: string)
          .metadata.permissionSet(permission: Permission): Promise<boolean>;

Parameters​

  • permission (Permission): Permission to apply.

Returns​

  • Promise<boolean>: Returns true when the permission policy is successfully updated for the collection. The new permissions take effect immediately and control read/write access for users based on their relationship to the collection (owner, group member, or other).