Get Started

Install Polybase DB

From Package Manager:

npm install @polybase/client

Initialize the library

  import { Polybase } from "@polybase/client";
 
  const db = new Polybase({
    defaultNamespace: "your-namespace",
  });

⚠️

Namespace must be used for collections.

If you specify a defaultNamespace, it will be automatically added for you when you create a collection instance.

Create a collection

⚠️

Note that reserved words and keywords (JavaScript) may not be used as identifiers (fields, function names etc.).

Please refer to this for the full list of reserved words (opens in a new tab).

You must create a collection before writing and reading data to Polybase DB. Create collections using Polybase DB Explorer (opens in a new tab) (recommended) or programatically using the JavaScript SDK.

Watch Shaki create a simple collection using the Polybase DB Explorer.

Here's an example Schema:

@public
collection City {
  id: string;
  name: string;
  country?: string;
 
  constructor (id: string, name: string) {
    this.id = id;
    this.name = name;
  }
 
  setCountry (country: string) {
    this.country = country;
  }
}

ℹ️

A Polybase DB collection is just like an Ethereum contract, but instead of being for a single record, collections describes the rules for a set of records.

Create a collection record

When you create a new record, the constructor function in your collection is called with the parameters you provide.

import { Polybase } from "@polybase/client";
 
const db = new Polybase({ defaultNamespace: "your-namespace" });
 
// Based on the collection code above, "new-york" is the `id` of the new record. 
// The `id` "new-york" must be unique (not already exist in the collection)
await db.collection("City").create(["new-york", "New York"]); 
// new-york is the `id`, New York is the `name`

ℹ️

Now go view the collection in the Polybase DB Explorer (opens in a new tab).

Update a collection record

You can update records by calling methods defined on your collection.

import { Polybase } from "@polybase/client";
 
const db = new Polybase({ defaultNamespace: "your-namespace" });
await db.collection("City").call("setCountry", ["USA"]);

Read a record

import { Polybase } from "@polybase/client";
 
const db = new Polybase({ defaultNamespace: "your-namespace" });
const data = await db.collection("City").record("new-york").get();

Live Example

Open in CodeSandbox (opens in a new tab)

View Schema for example (opens in a new tab) in explorer

Next steps

Understand Collections FAQ Read the Polybase DB Whitepaper

Introduction Collections