Start Trial

Starting with the CLI

How to get started using the DeltaStream command line interface

DeltaStream provides a Command Line Interface (CLI) you can use to interact with the platform from a terminal. This guide walks you through the steps to build a streaming application with DeltaStream’s CLI. Follow these steps to:

  • Get hands-on experience with foundational concepts in DeltaStream.

  • Gain the knowledge to build applications similar to the one in this guide.

While this guide uses topics in Apache Kafka, the steps should be the same regardless of whether you have data in other streaming data stores such as Amazon Kinesis or Redpanda.

Note If you prefer to use DeltaStream’s Web application, see Starting with the Web App for those details and procedures.

We assume you already have created your account and signed into DeltaStream. Also, we assume you already have created a DeltaStream organization or have joined an existing organization.

You accomplish the following steps in this guide for the CLI:

  • Download the DeltaStream CLI.

  • Connect to your streaming data store (in this case, Apache Kafka) by creating a data store in DeltaStream.

  • Create your first database.

  • Create streams and changelogs for your Kafka topics.

  • Create new streams, changelogs, and materialized views using DeltaStream’s continuous queries.

  • (Optional) Share your streaming data with other users in your organization.

Download the DeltaStream CLI

  1. Log into DeltaStream.

  2. At the bottom of the lefthand navigation, click Support Center ( ). The Support menu displays.

    Where to download the DeltaStream CLI

  3. Click the OS you want. The DeltaStream CLI begins downloading automatically into a dscli folder.

  4. Unzip and deploy the files as you would with any compressed application.

Launch the CLI

Get the API endpoint when you launch the CLI from the help section of the DeltaStream UI.

Note When you use the CLI for the first time, DeltaStream stores the --server flag in your user configuration, and you will not need it for future requests.

Create a Data Store

The first step is to create a data store in DeltaStream. A data store is a streaming service such as Apache Kafka or Amazon Kinesis where your streaming data resides.

Note The CLI refers to data stores simply as "stores."

Use the CREATE STORE statement to create a data store in the DeltaStream CLI:

Your new data store displays as the default data store in the prompt. Use the LIST STORES command to view the available data stores you have created in DeltaStream.

Note No default data store indicates in the prompt until you create your first data store.

As is indicated below, in declaring the data store, DeltaStream provides the required configurations to connect and use the streaming data store from DeltaStream.

You can now inspect the data store and print to view the content of its topics:

Create a Database

In DeltaStream, you use databases to organize your streaming data in an intuitive namespace. Use the CREATE DATABASE statement to create a database. When you create a database, DeltaStream in turn creates a default namespace, named public, in the database. The following shows the statement that creates a new database labelled TestDB:

The prompt displays the current database and namespace.

Create Streams and Changelogs

Now create DeltaStream objects on top of your Kafka topics. You do this using DeltaStream’s DDL statements.

Note In the CLI, you can use the SHOW command and the LIST command interchangeably.

To manage streaming data in an entity as an append-only stream, in which each streaming event is independent, define it as a stream. In the example below, you declare a stream on the ds_pageviews topic, as each pageview event is an independent event:

Note The DeltaStream UI uses the term OBJECTS instead of RELATIONS.

Next, declare a changelog for the ds_users topic. A changelog indicates that you wish to interpret events in an entity as UPSERT events. The events should have a primary key, and each event is interpreted as an insert or update for the given primary key. Use the CREATE CHANGELOG command to declare the users changelog:

Run Queries

Now that you have declared streams and changelogs, you can write continuous queries in SQL to process this streaming data in real time. Start with a Streaming or Continuous Query, wherein the query results stream back to you. You can use such queries to inspect your streams and changelogs, or to build queries iteratively by inspecting the query’s result.

Here's an example: Use the following interactive query to inspect the pageviews stream:

While interactive query results display, DeltaStream provides a Streaming or Continuous Query, wherein the query results are saved back in a store or a materialized view. To proceed, write a persistent query that joins the pageviews stream with the changelog to create an enriched pageviews stream that includes user details for each pageview event. While you're at it, also convert the epoch time to a timestamp with a time zone via the TO_TIMESTAMP_LTZ function.

During this time, DeltaStream compiles and launches the query as an Apache Flink streaming job.

You should be able to use the LIST QUERIES command to view the query along with its status:

When the query runs successfully, you have a new Kafka topic named csas_enriched_pv in your Kafka cluster, plus a new stream added to the streams in your TestDB database. To examine the contents of the new stream, run the following query:

Now that you have the enriched pageviews stream, you can build a materialized view in which you compute the number of pageviews per user. To create this materialized view, type the following statement:

When you run the above query, DeltaStream launches a streaming job that runs the SELECT statement and materializes the result of the query. To view this query, use the LIST QUERIES command:

You can query the resulting materialized view the same way you'd query a materialized view in a traditional relational database -- except that in DeltaStream, the streaming job always keeps the data in the materialized view fresh.

Below is a simple query to get the current view count for a user with the userid of User_2:

As you see, the number of pageviews for User_2 is 580 at the time you run the above query. Run the query again, and you see an updated result for the pageview count for the user. This demonstrates that every time you run a query on a materialized view, you receive the most up-to-date result. DeltaStream ensures the data in the view is continuously updated using the continuous query that declared the materialized view.

Now wait a few more seconds. Then run the same query on the materialized view. You should see something similar to the below:

As you see, the result is updated to 818 from the previous value of 580.

In summary, this guide has demonstrated how DeltaStream makes it easy to build a stream processing applications using the CLI. You've created a query that joins pageviews and users and creates a new stream called csas_enriched_pv. You also ran another query that creates a materialized view named user_view_count from csas_enriched_pv.

Clean Up

Now it's time to clean up your environment. To do this:

  1. Terminate the queries.

  2. Drop the created streams, changelogs, and materialized views.

  3. Go to the corresponding database and namespace to drop the streams, changelogs, and materialized views.

Important If there is a query that uses a stream, changelog, or materialized view, terminate the query before you drop the relation.

PreviousStarting with the Web AppNextCreate and Manage Data Stores

Last updated