← Back to Documentation

Getting Started

The best resource to get started with the Operand API. Learn how to create your first index, upsert your first documents, and perform search operations. This can be done via REST, or using one of our official SDKs.


Welcome to Operand! If you're reading this, you're probably interested in using Operand itself as an API in a product or service you're building.

You've come to the right place, in the next few minutes, we'll get you up and running with the basics of Operand.

What you'll do in this tutorial:

  • Create your account, if you haven't already done so.
  • Create your first index.
  • Get your API key.
  • Index your first object (and learn what objects are)!
  • Search for content within the object you indexed.

What you'll need:

  • A working JavaScript environment (i.e. Node.js installed).

(Note) This tutorial is written in JavaScript. If you're using a different language, please reach out. We can help you get started.

Step 1: Create your account

Login or Register for a new Operand account.

Click the verification link sent to your email, and you'll be redirected to the dashboard.

(Note) You do not need to enter a credit card to create an account, or get started with the Operand API. The first $10 of usage each month is free. To learn more, see pricing. If you go over your free quota, we'll (politely) reach out and ask you to configure billing.

Step 2: Create your first index

On the dashboard, under "Indexes", enter the name and description of your index, and click "Create Index".

You can name indexes anything you want, but we recommend using a name that is descriptive of the content you'll be indexing.

Note down the ID of the index (obtained by clicking on the index name in the list of indexes), as you'll need it in the next step. IDs are unique to each index, and look something like uqv1duxxbdxu.

Step 3: Get your API key

On the dashboard, under "API Keys", you can manage your API keys.

If you don't already have an API key, click "Create API Key". You'll need this for the next step.

Step 4: Index your first object

If you don't already have an environment set up for this tutorial, you can create one by doing the following commands:

mkdir operand-getting-started
cd operand-getting-started
npm init -y
npm install @operandinc/sdk

Inside of index.mjs, copy+paste the following:

import {
  operandClient,
  indexIDHeaderKey,
  ObjectService,
  Object,
} from "@operandinc/sdk";

(async () => {
  const operand = operandClient(
    ObjectService,
    "<your api key>",
    "https://api.operand.ai",
    {
      [indexIDHeaderKey]: "<your index id>",
    }
  );

  const website = await operand.upsert({
    type: Object.ObjectType.HTML,
    metadata: {
      value: {
        case: "html",
        value: {},
      },
    },
    properties: {
      properties: {
        _url: {
          indexed: false,
          value: {
            case: "text",
            value: "http://www.paulgraham.com/lesson.html",
          },
        },
      },
    },
  });
  console.log(website.toJsonString());
})();

Replace <your api key> and <your index id> with the values you obtained in the previous steps.

Run node index.mjs. You should see output similar to the following:

{"object":{"id":"wkzf8x05skxo","createdAt":"2022-11-14T06:26:38.592500Z","type":"OBJECT_TYPE_HTML","properties":{"properties":{"_url":{"indexed":false,"text":"http://www.paulgraham.com/lesson.html"}}},"status":"OBJECT_STATUS_INDEXING"}}

If you go to the index dashboard (dashboard -> "Indexes" -> click on your index), you should see the object you just indexed and its status.

There are a few possible statuses:

  • QUEUED: The object is queued for indexing.
  • INDEXING: The object is currently being indexed.
  • READY: The object has been indexed successfully.
  • ERROR: The object has failed to be indexed.

Once the HTML object has been indexed (i.e. its status is READY), you can search for content (see the next step).

Step 5: Search for content

To find the top-3 most relevant snippets of content from within the object we've indexed, we can do the following:

const results = await operand.searchWithin({
  query: "hacking tests",
  limit: 3,
});
console.log(results.matches.map((m) => `(${m.score}) ${m.content}`).flat());

If everything worked, you should see the following printed to the console:

[
  "(0.5365165) Hackable is the default for any test imposed by an authority. The reason the tests you're given are so consistently bad � so consistently far from measuring what they're supposed to measure � is simply that the people creating them haven't made much effort to prevent them from being hacked.",
  '(0.4821913) The kinds of work where you win by hacking bad tests will be starved of talent, and the kinds where you win by doing good work will see an influx of the most ambitious people. And as hacking bad tests shrinks in importance, education will evolve to stop training us to do it. Imagine what the world could look like if that happened.',
  "(0.47726515) Similarly, the fact that the tests were unhackable was a lot of what attracted me to startups. But again, I hadn't realized that explicitly."
]

Conclusion

Congratulations! You've just indexed your first object, and performed a search for content within it.

As always, if anything went wrong or you're looking for clarification on something, please feel free to reach out.

As some next steps, here are some other articles you might be interested in reading:

  • Augmenting LLMs with Knowledge: Learn how to use Operand to augment GPT-3 style prompts with additional, relevant knowledge.
  • Multi-Tenancy: Learn how to build multi-tenant applications with Operand. For example, a per-user knowledge base for a SaaS application.
  • Object Types: Learn about the different types of objects you can index with Operand.
  • Index Best Practices: Learn about best practices for indexing content with Operand, and keeping indexes up-to-date with new content.