Skip to main content

SDK Basics

This is the perfect starting point for developers looking to explore the SDK's core features. With easy-to-follow instructions presented in an interactive Stackblitz iframe for hands-on learning, you can quickly get up to speed with dcupl's powerful API.

Whether you're using dcupl with your own setup or a specific framework, our flexible API allows for seamless integration with any development environment.

info

This tutorial will teach you how to get started with dcupl and cover three important topics: initial setup, dcupl Query API, and dcupl List API.

  • In the initial setup, you will learn how to set up your dcupl environment, which includes installing necessary packages and configuring settings.

  • The dcupl Query API will teach you how to use the Query API to retrieve data from your dcupl instance. You will learn how to make queries, filter, page and sort data.

  • In the dcupl List API, you will learn how to use the List API to aggregate data, apply queries and work with a catalogue like API.

By learning these three topics, you will be able to get started with dcupl and use it to retrieve and manage data for your web applications.

Initial Setup​

Dcupl, written in TypeScript, operates seamlessly in any JavaScript/TypeScript environment, both on the client and server side. Integrate the dcupl SDK into your existing projects and harness its intuitive and robust API for querying data, computing facets, and aggregating thousands of data points within your frontend application.

Installation​

Simply install the dcupl SDK via npm:

npm i @dcupl/core

Setup​

In this introduction, we are using a simple Stackblitz TypeScript setup. The dcupl SDK code is independent of any JavaScript framework, so you can easily copy and paste the relevant code into your own IDE.

Explanation​

1) Imports​

We import the Dcupl class from @dcupl/core and some products from a static file. The products represent a simple JSON description of imaginary products generated with Chat GPT. It doesn't matter whether you fetch your data from an API or use static data - for the purposes of simplicity, we will import the data from another file, making it easy to get started with the dcupl SDK.

export const products = [
  {
    key: 'p1',
    name: 'Durable Backpack',
    price: 75,
    group: 'Backpacks',
    inStock: true,
  },
  ...
]

2) Create a new dcupl instance​

In most usecases you want to work with a single dcupl instance in your web application, incorporating multiple models and data streams. However, based on your needs, you can initialize as many instances as you want. Multiple dcupl instances do not share any common state and therefore do not interfere with one another.

If you're already familiar with the dcupl Console, you can add a configuration to connect your local instance with the dcupl Console, and subsequently, our CDN.

const dcupl = new Dcupl({
    config: {
        projectId: '...',
        apiKey: '...'
        version: 'draft'
    }
})

3) Add a model​

dcupl models play a crucial role in dcupl, as they describe the data loaded and processed within the SDK. Each entity (e.g., products, orders, receipts) is represented by a model. These models contain properties of various data types for type safety and basic validation, as well as references to other models, which define their relationships.

4) Add products data​

The SDK allows you to set, update, upsert, and delete data individually for each model. There is no specific limit to the amount of data you can add to dcupl. However, when building a data-intensive web application, several factors must be considered. We've written a blog post on this topic to help you determine the right amount of data for your particular use case. Some projects are calculating facets and aggregations using 300k+ datasets in live applications.

5) Init dcupl​

After adding your models and data, the final step in this example is to initialize dcupl. It will then work behind the scenes to create a dependency graph, set up initial data structures, and generate indexes for fast filtering, faceting, and aggregation based on the information provided by the models.

query API​

The dcupl Query API is your gateway to accessing data within a dcupl instance. A query statement contains all needed information to perform the query, including nested queries, paging, sorting, and data projection. We'll explore some utility functions later that aid in managing your query statements.



info

Find out more about the query API in our Understanding Queries Guide​

list API​

The final section of this tutorial focuses on DcuplLists and their supplementary functionalities for querying data. The code below demonstrates a common task of applying a filter to a list of datasets and computing aggregations.

Explanation​

1) Create a list​

A DcuplList is an instance of a specific model with added functionality like predefined filters and aggregations. You can initialize a list as a complete copy of the model, with fixed listItemKeys, a specific query, or based on an existing list. The list is stateful and manages the applying and removal of individual queries.

2) Apply your query​

In contrast to the global query API on the dcupl class, applying a query to a list is persistent. This stateful behavior is best suited for catalog-like applications where you gradually filter a large dataset to narrow down to your desired result.

3) Calculate Aggregations​

In addition to stateful queries, dcupl lists offer extra functionality that can be very useful in various applications, such as aggregations, grouped views, and calculating suggestions. Some of the aggregation outputs can be further processed by a query.many() call to obtain additional information.

4) List Metadata​

ListMetadata contains a lot of useful information about the list and the underlying model, like the currentSize, initialSize, appliedQuery, and available attributes. With this information, you can easily build a dynamic UI representation of your data models, similar to what we provide in the dcupl Console.

info

Whats next?​

From here on you have plenty of oportunities to choose from. Continue with one of our other tutorials, check out one of our videos or just browse the docs. Also take a look at our dcupl Console or just chat with us via our website.