Version 2.0

Execute Ontology Sql Query

POST/api/v2/sqlQueries/executeOntology

Warning

This endpoint is in preview and may be modified or removed at any time. To use this endpoint, add preview=true to the request query parameters.

Executes a SQL query against the Ontology. Results are returned synchronously in Apache Arrow format.

Third-party applications using this endpoint via OAuth2 must request the following operation scopes: api:sql-queries-execute api:ontologies-read.

Query parameters

preview

booleanoptional

Enables the use of preview functionality.

Request body

ExecuteOntologySqlQueryRequest

object

Hide child attributes

query

string

The SQL query to execute.

parameters

unionoptional

Parameters for the SQL query. Can be either unnamed positional parameters or a named parameter mapping.

Show child attributes

rowLimit

integeroptional

Maximum number of rows to return.

dryRun

booleanoptional

If true, parse and validate the query without executing it. Defaults to false.

branch

stringoptional

The Foundry branch to execute the query against. If not specified, the default (main) branch is used.

scenarioRid

stringoptional

The scenario to evaluate the query against. If not specified, no scenario is applied.

ontologyIdentifier

stringoptional

Either an ontology RID or an ontology API name.

tableProviders

map<TableName, ObjectSet>optional

Map of table providers, requires ontologyIdentifier to be provided otherwise it will throw.

Show child attributes

Response body

body

string

Examples

Request

Copied!

curl -X POST \
\t-H "Content-type: application/json" \
\t-H "Authorization: Bearer $TOKEN" \
	"https://$HOSTNAME/api/v2/sqlQueries/executeOntology?preview=true" \
	-d '{"query":"SELECT * FROM ri.ontology.main.object-type.xxx","scenarioRid":"ri.actions..scenario.0000-0000","branch":"ri.branch..branch.d827184f-ee0e-4351-8b70-efbe51e07252","ontologyIdentifier":"example-ontology"}'

Error responses

Error Name
`QueryParseError`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The query cannot be parsed.
	Parameters	`errorMessage`
`OntologyQueryFailed`	Error Code	`INTERNAL`
	Status Code	500
	Description	The Ontology query failed.
	Parameters	`errorMessage`
`OntologyQueryInvalidObjectBackend`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The ontology query references object types or link types indexed in Object Storage V1, which is incompatible with Ontology SQL. Migrate the entities to Object Storage V2 or remove them from the query.
	Parameters	`objectTypeRids, linkTypeRids`
`OntologyQueryNestedObjectSetTooLarge`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The query references too many objects across joins, link lookups, or sub-queries. Narrow the scope (add filters, reduce joins, restrict object types) and retry. The actual and maximum object counts are returned as parameters.
	Parameters	`nestedObjectSetSize, maxAllowedNestedObjectSetSize`
`OntologyQueryStringColumnTooLong`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	A string column in the query result contains a value larger than the platform's per-cell size limit. Exclude or filter the column, or scope the query to skip the oversized rows.
	Parameters	`columnName`
`OntologyObjectTypeNotFound`	Error Code	`NOT_FOUND`
	Status Code	404
	Description	The ontology query referenced an object type RID that does not exist or is not visible to the requesting user. Verify the RID (e.g. via list-object-types or get-object-type-details) and retry.
	Parameters	`objectTypeRid`
`ExecuteOntologySqlQueryPermissionDenied`	Error Code	`PERMISSION_DENIED`
	Status Code	403
	Description	Could not executeOntology the SqlQuery.
	Parameters

See Errors for a general overview of errors in the platform.