๐ŸŽฏAPI Stability
Short-TermThis API may change in future versions. Use with caution in production environments.

Summary

The formatQuery() GraphQL query formats a syntactically valid query string to a given column width guideline. The formatter breaks syntax nodes that exceed the guideline width into multiple lines when possible, though individual tokens such as bare words may still exceed the target width. Formatting is verified to preserve the meaning of the query. If the query cannot be formatted, the formattedQuery field returns null and the diagnostics field contains error-severity messages explaining why.

Syntax

graphql
formatQuery(
      input: FormatQueryArguments!
   ): QueryFormattingInfo!

The query accepts a required input argument of type FormatQueryArguments. Supply the required queryString and optionally set width to control the column width guideline. The default width is 120 characters. The query returns a non-null QueryFormattingInfo object containing the formatted query string and any formatting diagnostics.

Example

Raw
graphql
query {
  formatQuery(
    input: {
      queryString: "groupBy([#type,actor.type]) | count() | sort(count, order=desc)",
      width: 80
    }
  ) {
    formattedQuery
    diagnostics { errors { message } }
  }
}
Mac OS or Linux (curl)
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "query {
  formatQuery(
    input: {
      queryString: \"groupBy([#type,actor.type]) | count() | sort(count, order=desc)\",
      width: 80
    }
  ) {
    formattedQuery
    diagnostics { errors { message } }
  }
}"
}
EOF
Mac OS or Linux (curl) One-line
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "query {
  formatQuery(
    input: {
      queryString: \"groupBy([#type,actor.type]) | count() | sort(count, order=desc)\",
      width: 80
    }
  ) {
    formattedQuery
    diagnostics { errors { message } }
  }
}"
}
EOF
Windows Cmd and curl
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json" ^
    -d @'{"query" : "query { ^
  formatQuery( ^
    input: { ^
      queryString: \"groupBy([#type,actor.type]) | count() | sort(count, order=desc)\", ^
      width: 80 ^
    } ^
  ) { ^
    formattedQuery ^
    diagnostics { errors { message } } ^
  } ^
}" ^
} '
Windows Powershell and curl
powershell
curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "query {
  formatQuery(
    input: {
      queryString: \"groupBy([#type,actor.type]) | count() | sort(count, order=desc)\",
      width: 80
    }
  ) {
    formattedQuery
    diagnostics { errors { message } }
  }
}"
}'
    "$YOUR_LOGSCALE_URL/graphql"
Perl
perl
#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $query = "query {
  formatQuery(
    input: {
      queryString: \"groupBy([#type,actor.type]) | count() | sort(count, order=desc)\",
      width: 80
    }
  ) {
    formattedQuery
    diagnostics { errors { message } }
  }
}";
$query =~ s/\n/ /g;
my $json = sprintf('{"query" : "%s"}',$query);
my $req = HTTP::Request->new("POST", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");

$req->content( $json );

my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";
Python
python
#! /usr/local/bin/python3

import requests

url = '$YOUR_LOGSCALE_URL/graphql'
mydata = r'''{"query" : "query {
  formatQuery(
    input: {
      queryString: \"groupBy([#type,actor.type]) | count() | sort(count, order=desc)\",
      width: 80
    }
  ) {
    formattedQuery
    diagnostics { errors { message } }
  }
}"
}'''

resp = requests.post(url,
                     data = mydata,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)
Node.js
javascript
const https = require('https');

const data = JSON.stringify(
    {"query" : "query {
  formatQuery(
    input: {
      queryString: \"groupBy([#type,actor.type]) | count() | sort(count, order=desc)\",
      width: 80
    }
  ) {
    formattedQuery
    diagnostics { errors { message } }
  }
}"
}
);


const options = {
  hostname: '$YOUR_LOGSCALE_URL',
  path: 'graphql',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
    Authorization: 'BEARER ' + process.env.TOKEN,
    'User-Agent': 'Node',
  },
};

const req = https.request(options, (res) => {
  let data = '';
  console.log(`statusCode: ${res.statusCode}`);

  res.on('data', (d) => {
    data += d;
  });
  res.on('end', () => {
    console.log(JSON.parse(data).data);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();
Example Responses
Success (HTTP Response Code 200 OK)
json
{
  "data": {
    "formatQuery": {
      "formattedQuery": "groupBy([#type, actor.type])\n| count()\n| sort(count, order=desc)",
      "diagnostics": {
        "errors": []
      }
    }
  }
}

The example supplies a compact single-line query. The response shows the formatted result broken across multiple lines to fit within the default 120-character width, along with empty diagnostics confirming no formatting errors occurred.

Input Parameters

The required queryString is the query to format. The optional width sets the column width guideline in characters; nodes that exceed this limit are broken into multiple lines when possible. The default width is 120. The input parameters are listed here:

Returned Values

The result contains two fields: formattedQuery holds the formatted query string, or null if the query could not be formatted; and diagnostics holds parse and format diagnostic messages, including error-severity messages when formatting fails. The available fields are listed here: