Write Data in Real Time with the apperate.write() JS Method

Apperate’s iex.js JavaScript library (iexjs) makes writing data a snap by wrapping Apperate’s Data API in JavaScript methods. The apperate.write() iexjs method is optimized for writing small amounts of data (e.g., one or a few records) quickly.

Here, for example purposes, we’ll call apperate.write() within the RunKit npmjs environment.

If you want to use iexjs in a NodeJS environment, you can install iexjs with npm.

npm install @apperate/iexjs

Note

iexjs can also run in the browser via native fetch and eventsource, or from node via cross-fetch and eventsource.

Prerequisite

IEX Cloud Apperate account - Create one here.

Call apperate.write()

Here’s how to write data using the apperate.write() iexjs JavaScript library method.

1. Open the RunKit npmjs environment.

   

2. Copy the following code into your RunKit editor and replace the CAPITALIZED parameter values mentioned below.

   Code:

   const {Client} = require("@apperate/iexjs")
   const client = new Client({api_token: "SECRET_TOKEN", version: "VERSION"});
   client.apperate.write({
       workspace: "WORKSPACE", 
       id: "DATASET", 
       createDatasetOnDemand: true, 
       data: [{"firstname": "Jasmine", "lastname": "Doe", "email": "jasmine.doe@foo.org", "org": "Foo LLC"}]})
           .then((res) => {
               console.log(res);
           });
   

   The first two lines of code import the iexjs Client definition and instantiate it. The apperate.write method call writes data from the data parameter into the target dataset specified by the id and workspace parameters. The createDatasetOnDemand: true setting (optional) instructs Apperate to create the dataset if it doesn’t exist already.

   Replace in the Code

   Placeholder	Replace with …
   SECRET_TOKEN	Your secret API token
   VERSION	Apperate API version (v1 is the current version)
   WORKSPACE	Your workspace name
   DATASET	Target dataset ID (the ID of an existing dataset to populate or a new dataset to create)

   See also

   The Write Data reference page describes the underlying POST /record method and its parameters.

3. Run the code. Apperate writes the data record to the target dataset and returns a response like this:

   {success: true, message: "wrote 2 messages"}
   

   If the dataset doesn’t exist already, Apperate creates a new dataset, giving it the name you specified and inferring its schema from the data you provided.

Here’s what the response looks like in RunKit.

That was fast and easy, right?! Let’s examine the generated dataset.

Check the Generated Dataset

1. Go to the Console.

2. In the DATASETS section in the navigation, your new dataset appears under your workspace name. If only your workspace name shows, click your workspace name to expand the listing.

   

3. Click on the name of the dataset. The dataset database page appears.

   

4. Click Edit. The schema editor appears.

   

   Apperate made a best effort to determine your data types and properties to index. But let’s adjust the schema to better fit the data and how we want to use it. Since email addresses are unique and lastnames are a good secondary identifier, let’s use them as the dataset’s Primary Index (aka key) and Secondary Index (subkey), respecfively.

5. Make email the Primary index and lastname the Secondary index.

   

6. Save your changes by clicking Update Dataset.

   Note

   You can update the schema as you like. See Modify a Data Schema for details.

7. Go to the overview page and view the dataset’s docs by clicking Open Docs.

   

   Notice that the Response Attributes email and lastname are labeled *key and *subkey. This shorthand indicates they’re your Primary and Secondary indexes.

   Note

   A dataset’s API docs indicate all applicable data indexes (e.g., key, subkey, date).

Let’s search the target dataset for the data you wrote using the email and lastname values as key and subkey values.

Query the Data

You can query the data just as easily as you wrote it. Let’s retrieve a data record using the iexjs library’s apperate.queryData method.

1. In your app or RunKit, enter the following code to query on the user’s email address and last name. Make sure to replace the CAPITALIZED values too.

   Code:

   const {Client} = require("@apperate/iexjs")
   const client = new Client({api_token: "SECRET_TOKEN", version: "VERSION"});
   client.apperate.queryData({
       workspace: "WORKSPACE", 
       id: "DATASET", 
       data: [{"key": "jasmine.doe@foo.org", "subkey": "Doe"}]})
           .then((res) => {
               console.log(res);
   });
   

   The apperate.queryData method’s data parameter takes an object array that includes a key index, and may also include a subkey and/or date index. To get the data record we wrote earlier, our apperate.queryData call above passes in an email address as a key index value and a lastname as the subkey index value.

2. Run the code. Apperate returns the matching record in a query response and prints it.

Here’s what the query response looks like in RunKit.

Writing and reading data in Apperate is just that easy! Congratulations on using Apperate in JavaScript via iexjs!

What’s Next

Now that you know how to write data, here are some topics to consider next:

Filter on Custom Dataset Events guides you in configuring alerts on important incoming data events.

Search Data: These articles show various ways to query data.

Managing Your Data: These guides explain dataset schema fundamentals, creating views, and creating datasets via the Datasets API.

Production-Ready IEX Cloud Core Financial Data: Introduces Apperate’s 5+ terabytes of built-in financial data available for enriching your fintech applications.

Connect to Data: These tutorials show you how to connect to data from a URL, an AWS S3 bucket, a MySQL database, Coinbase, Ethereum, and more.