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.
Open the RunKit npmjs environment.
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. Theapperate.write
method call writes data from thedata
parameter into the target dataset specified by theid
andworkspace
parameters. ThecreateDatasetOnDemand: 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.
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#
Go to the Console.
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.
Click on the name of the dataset. The dataset database page appears.
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.
Make
email
the Primary index andlastname
the Secondary index.Save your changes by clicking Update Dataset.
Note
You can update the schema as you like. See Modify a Data Schema for details.
Go to the overview page and view the dataset’s docs by clicking Open Docs.
Notice that the Response Attributes
email
andlastname
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.
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’sdata
parameter takes an object array that includes akey
index, and may also include asubkey
and/ordate
index. To get the data record we wrote earlier, ourapperate.queryData
call above passes in an email address as akey
index value and a lastname as thesubkey
index value.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.