GQL Resource

This resource executes a GS SQL statement and returns the results.

It is not api_key compatible because GS SQL execution requires running under a user so that results are filtered by content store permissions.

GET gql

---

Executes a GS SQL statement and returns the results.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key compatible?	No

Parameters

s	required	The URL encoded GS SQL statement.
tz	optional	The time zone id to use if the SQL returns dynamic rolllup samples or if any date functions do not include a time zone id.
h	optional	true/false. Defaults to false. Indicates if the result contains the header. Only applies to compact (c=true) queries.
c	optional	true/false. Defaults to false. Indicates if the result is returned in a JSON compact format.

Example Requests

Request
Execute the following GS SQL statement. Return column headers. Return compact format. Notice that the GS SQL is encoded:
Select cname, name, folderPath from Stream Where StartsWith(folderPath, '/Components')

gql?org=00000000-0000-0000-0000-000000000001&c=true&h=true&tz=US%2FCentral&s=select%20cname%2C%20name%2C%20folderPath%20from%20stream%20where%20StartsWith(folderPath%2C%20%27%2FComponents%27)

Response Body
{
   "success": true,
   "message": "",
   "cols": [
      {
         "valueType": "STRING",
         "name": "cname"
      },
      {
         "valueType": "STRING",
         "name": "name"
      },
      {
         "valueType": "STRING",
         "name": "folderPath"
      }
      ],
   "rows": [
      [
         "Refrigerator Smart Plug Sensor",
         "Ongoing Monthly Cost (Euros)",
         "/Components"
      ],
      [
         "Refrigerator Smart Plug Sensor",
         "cost - dollars",
         "/Components"
      ],
      [
         "Refrigerator Smart Plug Sensor",
         "current - rolling 3pt avg",
         "/Components"
      ],
      [
         "Refrigerator Smart Plug Sensor",
         "current",
         "/Components"
      ],
      [
         "Garage Temperature and Light Sensor",
         "light",
         "/Components"
      ],
      [
         "Garage Temperature and Light Sensor",
         "low_battery",
         "/Components"
      ]
   ]
}


Request
Execute the following GS SQL statement. Return not in the compact format. Notice that the GS SQL is encoded:
select _component_name, _name, _folder_path from system.stream where StartsWith(_folder_path, '/Components') order by _component_name limit 3

gql?org=00000000-0000-0000-0000-000000000001&c=false&h=true&tz=US%2FCentral&s=select%20 cname%2C%20name%2C%20folderPath%20from%20stream%20where%20StartsWith(folderPath%2C%20%27%2FComponents%27)%20order%20by%20cname%20limit%203&_dc=1648578504815

Response Body
{
  "success": true,
   "message": "",
  "rows": [
    {
      "folderPath": "/Components",
      "cname": "Currency Exchange Rates",
      "name": "EUR/USD Conversion Rate"
    },
    {
      "folderPath": "/Components",
      "cname": "Garage Temperature and Light Sensor",
      "name": "light"
    },
    {
      "folderPath": "/Components",
      "cname": "Garage Temperature and Light Sensor",
      "name": "low_battery"
    }
  ]
}

POST gql

---

Executes a GS SQL statement passed in the request body and returns the results. Use this method for large statements that may exceed URL length limits.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key compatible?	No

Query String Parameters

tz	optional	The time zone id to use if the SQL returns dynamic rolllup samples or if any date functions do not include a time zone id.
h	optional	true/false. Defaults to false. Indicates if the result contains the header. Only applies to compact (c=true) queries.
c	optional	true/false. Defaults to false. Indicates if the result is returned in a JSON compact format.

Request Body

The GS SQL statement as plain text. The statement does not need to be URL encoded.

Example Requests

curl Example
Execute a GS SQL statement via POST. The statement is passed as the request body:

curl -X POST "https://grovestreams.com/api/gql?org=00000000-0000-0000-0000-000000000001&c=true&h=true&tz=US/Central" \
  -H "Cookie: JSESSIONID=your_session_id" \
  -d "select _component_name, _name, _folder_path from system.stream where StartsWith(_folder_path, '/Components')"

Response Body
The response format is identical to the GET method.

POST gql/import_file

---

Uploads and executes a file containing multiple semicolon-delimited GS SQL statements. Statements are executed sequentially. A system notification is created upon completion summarizing the results. See File Import for file format details.	Resource Information
	Rate Limited?	Yes
	session and oauth token compatible?	Yes
	api_key compatible?	No
	Content-Type	multipart/form-data

Parameters

continueOnError

optional

true/false. Defaults to false. When false, execution stops at the first statement that fails. When true, all statements are executed and errors are collected.

Request Body

A multipart/form-data request containing a single UTF-8 encoded text file with semicolon-delimited GS SQL statements. Maximum file size: 1 MB.

Example Request

curl Example
Upload and execute a SQL file:

curl -X POST "https://grovestreams.com/api/query/import_file?org=ORG_UID" \
  -H "Cookie: JSESSIONID=your_session_id" \
  -F "file=@setup.sql"

With continueOnError:

curl -X POST "https://grovestreams.com/api/query/import_file?org=ORG_UID&continueOnError=true" \
  -H "Authorization: Bearer your_oauth_token" \
  -F "file=@setup.sql"

Response Body (all statements succeeded)
{
   "success": true,
   "totalStatements": 3,
   "successCount": 3,
   "failureCount": 0,
   "totalElapsedMs": 245,
   "stoppedOnError": false,
   "statements": [
      {
         "statementNumber": 1,
         "lineNumber": 1,
         "statement": "CREATE TABLE sensor (temperature DOUBLE, humidity DOUBLE)",
         "success": true,
         "elapsedMs": 120
      },
      {
         "statementNumber": 2,
         "lineNumber": 3,
         "statement": "INSERT INTO sensor (cname, temperature) VALUES ('Sensor_A', 22.5)",
         "success": true,
         "elapsedMs": 85
      },
      {
         "statementNumber": 3,
         "lineNumber": 5,
         "statement": "SELECT cname, temperature FROM sensor",
         "success": true,
         "rowCount": 1,
         "elapsedMs": 40
      }
   ]
}


Response Body (error on statement 2, stopped)
{
   "success": false,
   "totalStatements": 3,
   "successCount": 1,
   "failureCount": 1,
   "totalElapsedMs": 130,
   "stoppedOnError": true,
   "statements": [
      {
         "statementNumber": 1,
         "lineNumber": 1,
         "statement": "SELECT cname FROM stream LIMIT 1",
         "success": true,
         "rowCount": 1,
         "elapsedMs": 95
      },
      {
         "statementNumber": 2,
         "lineNumber": 2,
         "statement": "SELECT bad_col FROM bad_table",
         "success": false,
         "error": "Table 'bad_table' not found",
         "elapsedMs": 35
      }
   ]
}