Raw Queries & Subscriptions

While the @blocklet/server-js library provides convenient helper methods for most common GraphQL operations, there are situations where you might need more flexibility or access to features not yet exposed through the SDK. For these advanced use cases, the library allows you to execute raw GraphQL queries and subscriptions directly.

This approach is ideal when you need to construct highly specific queries, access the latest API features before they are officially wrapped, or optimize data fetching beyond what the standard methods offer.

Raw Queries#

The doRawQuery method enables you to send any valid GraphQL query string to the Blocklet Server API endpoint. This gives you complete control over the data you request and its structure.

Example#

Here's how to use doRawQuery to fetch basic information about the connected node.

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function getNodeVersion() {
  try {
    const query = `{
      getNodeInfo {
        info {
          version
          name
        }
      }
    }`;

    const result = await client.doRawQuery(query);
    console.log('Node Name:', result.getNodeInfo.info.name);
    console.log('Node Version:', result.getNodeInfo.info.version);
  } catch (error) {
    console.error('Failed to execute raw query:', error);
  }
}

getNodeVersion();

Example Response

{
  "getNodeInfo": {
    "info": {
      "version": "1.8.22",
      "name": "My Dev Node"
    }
  }
}

This method returns a promise that resolves with the exact JSON data returned by the GraphQL server, allowing you to access nested properties directly.

Raw Subscriptions#

For real-time data updates, you can use the doRawSubscription method to establish a persistent connection and listen for server-pushed events. Unlike a standard query, this method returns a subscription object that allows you to register event listeners.

Example#

This example demonstrates how to subscribe to blocklet status changes. The subscription will push new data whenever a blocklet's status is updated (e.g., from 'running' to 'stopped').

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function watchBlockletStatus() {
  try {
    const subscriptionQuery = `subscription {
      blockletStatusChanged {
        did
        status
      }
    }`;

    const subscription = await client.doRawSubscription(subscriptionQuery);

    subscription.on('data', (data) => {
      const { did, status } = data.blockletStatusChanged;
      console.log(`Blocklet ${did} status changed to: ${status}`);
    });

    subscription.on('error', (err) => {
      console.error('Subscription error:', err);
    });

    console.log('Listening for blocklet status changes...');

Example Data Stream

When a blocklet's status changes, the data event listener will receive a payload like this:

{
  "blockletStatusChanged": {
    "did": "z8iZpA6x3M4Jz3J6iK9y6L4oE3nF2aH5c8g7",
    "status": "stopped"
  }
}

Using raw queries and subscriptions provides a powerful way to interact with the Blocklet Server API when the standard helper methods don't meet your specific needs. For troubleshooting your raw queries or any other client interactions, proceed to the next section on Debugging.