Add Stream metadata

You can add arbitrary string metadata to any stream. You can also create a new stream by sending metadata using a stream ID that does not already exist. This is mainly used when retrieving persisted data using the Query API, but is also displayed in Data Explorer. This helps you identify data of interest.

How to add metadata to a stream

Send a PUT request to the following endpoint to update a stream with the given properties:

/topics/${topicName}/streams/${streamId}

You should replace ${topicName} with the name of the topic your stream belongs to, and ${streamId} with the id of the stream you wish to update. For example:

/topics/cars/streams/66fb0a2f-eb70-494e-9df7-c06d275aeb7c

Tip

You can create a new stream by supplying a ${streamId} that doesn’t already exist. It will be initialized with the data you provide in the payload, and the ID you use in the endpoint. This avoids the need to call the create stream endpoint separately.

Your request should contain a payload consisting of JSON data containing the desired metadata.

Example request

Below is an example payload demonstrating how to set a single item of metadata. Note that the metadata property references an object which contains key/value string-based metadata.

curl

curl "https://${domain}.platform.quix.io/topics/${topicName}/streams/${streamId}" \
     -X PUT \
     -H "Authorization: bearer ${token}" \
     -H "Content-Type: application/json" \
     -d '{"metadata":{"fruit":"apple"}}'

Node.js

const https = require('https');

const data = JSON.stringify({ metadata: { fruit: "apple" }});

const options = {
    hostname: domain + '.platform.quix.io',
    path: '/topics/' + topicName + '/streams/' + streamId,
    method: 'PUT',
    headers: {
        'Authorization': 'Bearer ' + token,
        'Content-Type': 'application/json'
    }
};

const req = https.request(options);

req.write(data);
req.end();

Since this is a PUT request, it will replace all the stream data with the payload contents. To maintain existing data, you should include it in the payload alongside your metadata, for example:

{
    "name": "Example stream",
    "location": "/sub/dir",
    "metadata": {
        "fruit": "apple"
    }
}

Response

No payload is returned from this call. A 200 HTTP response code indicates success. If the call fails, you should see either a 4xx or 5xx response code indicating what went wrong. For example, you’ll see a 405 code if you forget to specify the correct PUT method.

Using SignalR

var signalR = require("@microsoft/signalr");
const token = "YOUR_TOKEN"
const environmentId = "YOUR_ENVIRONMENT_ID"
const topic = "YOUR_TOPIC_NAME"
const streamId = "ID_OF_STREAM_TO_UPDATE"

const options = {
    accessTokenFactory: () => token
};

const connection = new signalR.HubConnectionBuilder()
    .withUrl("https://writer-" + environmentId + ".platform.quix.io/hub", options)
    .build();

// Establish connection
connection.start().then(async () => {
    console.log("Connected to Quix.");

    // Note, SignalR uses the same models as the HTTP endpoints, so if in doubt, check HTTP endpoint samples or Swagger for model.
    let streamDetails = {
        "name": "Example stream",
        "location": "/sub/dir",
        "metadata": {
            "fruit": "apple"
        }
    }

    // Send stream update details
    console.log("Updating stream");
    await connection.invoke("UpdateStream", topic, streamDetails);
    console.log("Updated stream");
});

Tip

Also available as JsFiddle at https://jsfiddle.net/QuixAI/ruywnz28/

🏃‍♀️ Next step

Send parameter data