Key-Value Database

Setup

Here is how to use the Key-Value Database service of the Crewdle SDK. Each user wanting to join must open a database with the same name and provide a layout.

To generate a layout you can either do it in JSON format or use our LayoutBuilder.

Both layout and layoutJSON are valid ways to write a layout in the Crewdle SDK and both return the same thing.

import { DatabaseEvent, IValueType } from '@crewdle/web-sdk-types';
import { LayoutBuilder, QueryBuilder } from '@crewdle/web-sdk';

const layout = LayoutBuilder.layout(4)
layout
  .table('first-table')
  .index('secondary-key')
layout
  .table('second-table')
  .index('secondary-key')
  .index('additional-index')

const layoutJSON = {
  tables: {
    'first-table': {
      indexes: [
        { keyPath: 'secondary-key' },
      ],
    },

    'second-table': {
      indexes: [
        { keyPath: 'secondary-key' },
        { keyPath: 'addtional-index' }
      ],
    },
  },

  version: 4,
}

const keyValueDB = await cluster.openKeyValueDatabase('keyValueDatabase', layout);

You can then subscribe to database events.

keyValueDB.subscribe(async (event) => {
  switch (event.event) {
  case DatabaseEvent.SyncComplete:
    console.log('SyncComplete')
    break;
  }
});

When you no longer need to interact with the database, you can either unsubscribe from the Key-Value database or close it altogether.

keyValueDB.unsubscribe();

keyValueDB.close();

Interact with a table

You can retrieve tables from the Key-Value Database. The interface must extend IValueType as is it a Base interface for all value types. Value types define the value of objects in a IDatabaseTable.

interface FirstTableType extends IValueType {
  secondaryKey: string;
  data: string | string[]
}

const firstTable = keyValueDB.getTable<FirstTableType>('first-table');

And then subscribe to the changes in the table.

firstTable.subscribe((event) => {
  switch (event.action) {
    case 'add':
      console.log('AddAction');
      break;
    case 'update':
      console.log('UpdateAction');
      break;
    case 'delete':
      console.log('DeleteAction');
      break;
  }
});

In the following snippet, query will list values where their 'secondary-key' index equals 'crewdle-key' and will give you a limit of 3 results in ascending order, ignoring the first result due to the offset. queryJSON is equivalent but in JSON format. The SDK accepts both syntaxes.

const query = QueryBuilder
  .index('secondary-key')
  .where('==', 'crewdle-key')
  .orderBy('asc')
  .limit(3)
  .offset(1);

const queryJSON = {
  where: {
    key: 'secondary-key',
    operator: '==',
    value: 'crewdle-key'
  },
  orderBy: {
    key: 'secondary-key',
    direction: 'asc'
  },
  limit: 3,
  offset: 1,
}

const value = { secondaryKey: 'crewdle-key', data: 'Entering data in the database' };
const key = 'secondary-key';

// Add a value to the first table
const firstObject = await firstTable.add(value);
// Get the object by ID in the first table
const findObjectID = await firstTable.get(firstObject.id);
// Set to the variable value the value at a specified key
await firstTable.set(key, value);

// List the correct values according to a specified query
await firstTable.list(query);
// Count the number of keys in the first table
await firstTable.count();

// Delete a specified key
await firstTable.delete(key);
// Clear the first table
await firstTable.clear();

When you no longer need to interact with the table, you can unsubscribe from it.

firstTable.unsubscribe();

Additional Resources

See the Getting Started section for more information about initiating the SDK and a cluster.

To see a full example of a Key-Value Database being used, checkout our Key-Value Database sample. For more information on the services used in this page, head to our SDK reference