Create a Collection

The zkDatabase library provides the functionality to create a collection, which serves as a structured grouping of documents similar to a table in a relational database. In a zkDatabase, each collection is defined by a schema that allows the representation of data both as human-readable JSON and in a cryptographically provable format suitable for zero-knowledge (ZK) circuits. This dual representation ensures data is both easily manageable and secure, supporting advanced privacy-preserving operations.

Definition

When creating a collection, you need to specify a schema that dictates the structure and data types of the documents. This schema ensures that all documents within the collection are consistent and integrate seamlessly with cryptographic operations.

import { Schema, SchemaToObject } from '@zkdb/common';

const schema = new Schema([
  { name: 'fieldName', kind: 'FieldType' },  
  // ... more fields
]);

Defining Schema Type

You need to define a TypeScript type that matches your schema to ensure type safety when interacting with the collection. There are two ways to do this:

Option 1: Infer from Schema

You can automatically infer the type from your schema definition using SchemaToObject. This ensures your type is always in sync with your schema.

type SchemaType = SchemaToObject<ReturnType<typeof schema.schemaDefinition>>;

Option 2: Manual Definition

Alternatively, you can manually define the interface. Ensure the fields match your schema exactly.

type SchemaType = {
  myField: string;
  // ... match other fields
};

Creating the Collection

Once you have your schema and type, pass them to the create method:

const result = await zkdb.db(databaseName)
    .collection<SchemaType>(collectionName)
    .create(schema, permission, groupName);

Schema Definition

Schemas are created using the Schema class from @zkdb/common. Available field types include:

• String - For text fields
• UInt32 - For 32-bit unsigned integers
• Int64 - For 64-bit signed integers
• Bool - For boolean values
• Field - For raw field elements

Parameters

• schema (Schema): The predefined structure for the collection, detailing the data types and constraints for its documents.
• permission (Permission): An object that defines the permissions for accessing and manipulating the collection.
• groupName (string): The name of the group associated with this collection.

Returns

The operation returns a Result that resolves upon successful establishment of the collection. Use .unwrap() to get the value or check with .isOk() / .isErr().

Example

Here is an example of creating a collection in the zkDatabase:

import { ZkDatabase } from 'zkdb';

const zkdb = new ZkDatabase({
  apiKey: 'zkdb_536aac02a1b7.c001b6b8f...da3aa4185d8d2ad07f0ae94aT',
  // This URL is for test environment
  url: "https://serverless.zkdatabase.org/graphql", 
});
// Create new group for user chiro-user
(await zkdb.db('zkdb_test').group('chiro').create({
  groupDescription: 'Test group',
})).unwrap();

// Define the schema for given collection
const ShirtSchema = new Schema([
  { name: 'name', kind: 'String' },
  { name: 'price', kind: 'UInt64' },
]);

// Create a new collection with the defined schema
const result = (await zkdb.db('zkdb_test')
  .collection('test_collection')
  .create(
    ShirtSchema,
    Permission.policyPrivate(),
    'chiro'
  )).unwrap();

console.log('Collection created:', result);

const result2 = (await zkdb.db('zkdb_test').collection('test').create(ShirtSchema)).unwrap();
console.log('Collection created:', result2);