Skip to main content

Collection Index

Index management for a collection via collection(name).index.

List Indexes​

Use this to fetch all indexes defined on a collection. Helpful for auditing existing indexes, understanding query strategies, and capacity planning.

Definition​

await zkdb.db(databaseName: string)
          .collection(collectionName: string)
          .index.list(): Promise<TIndexListResponse[]>;

Parameters​

  • None

Returns​

  • Promise<TIndexListResponse[]>: Returns an array of all indexes created on the collection, including their names, performance statistics (size, access count), uniqueness constraints, and column specifications. This provides complete visibility into the collection's indexing strategy for query optimization.
type TIndexListResponse = {
  indexName: string;
  size: number;
  access: number;
  createdAt: Date;
  unique: boolean;
  property: "Compound" | "Single";
  index: Array<{ column: string; order: ESortOrder }>;
};

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 collectionBook = dbTest.collection('Shirt');
const idx = await collectionBook.index.list();
console.log('Existing indexes:', idx);

await zkdb.auth.signOut();

Result:​

[
  {
    "indexName": "idx_shirt_name",
    "size": 16384,
    "access": 42,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "unique": false,
    "property": "Single",
    "index": [
      { "column": "name", "order": "Asc" }
    ]
  },
  {
    "indexName": "idx_shirt_name_price",
    "size": 24576,
    "access": 10,
    "createdAt": "2024-01-02T00:00:00.000Z",
    "unique": false,
    "property": "Compound",
    "index": [
      { "column": "name", "order": "Asc" },
      { "column": "price", "order": "Desc" }
    ]
  }
]

Create Indexes​

Create single or compound indexes to optimize query performance on one or multiple fields. You can also enforce uniqueness on a set of fields when needed.

Definition​

await zkdb.db(databaseName: string)
          .collection(collectionName: string)
          .index.create(index: TCollectionIndex[]): Promise<boolean>;

Parameters​

  • index (Array): Array of index specs, e.g. { index: { name: ESortOrder.Asc }, unique: false }.
type TCollectionIndex = {
  index: Record<string, ESortOrder>;
  unique: boolean;
};

Returns​

  • Promise<boolean>: Returns true when the index is successfully created on the specified columns. The index immediately becomes available for query optimization, improving performance for searches, sorts, and filters on the indexed fields.

Example​

import { ZkDatabase } from 'zkdb';
import { ESortOrder } from '@zkdb/common';

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 collectionBook = dbTest.collection('Shirt');
await collectionBook.index.create([{ index: { name: ESortOrder.Asc }, unique: false }]);

await zkdb.auth.signOut();

Drop Index​

Remove an existing index by its name. This is useful when an index is no longer needed, consumes unnecessary storage, or impacts write performance.

Definition​

await zkdb.db(databaseName: string)
          .collection(collectionName: string)
          .index.drop(indexName: string): Promise<boolean>;

Parameters​

  • indexName (String): The name of the index to drop.

Returns​

  • Promise<boolean>: Returns true when the index is successfully deleted from the collection. Once dropped, the index is no longer available for query optimization and queries may experience slower performance on the previously indexed fields.

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 collectionBook = dbTest.collection('Shirt');
await collectionBook.index.drop('idx_shirt_name');

await zkdb.auth.signOut();