openapi: 3.1.0 info: contact: name: Contact Us url: https://data.world/company/contact-us termsOfService: https://data.world/terms-policies title: data.world Public catalog relationships queries API version: '0' description: Manage relationships between catalog resources servers: - url: /v0 security: - bearerAuth: [] tags: - name: queries paths: /cancel: post: description: Cancel a running query. operationId: cancel parameters: - in: query name: queryruntoken required: true schema: type: string minLength: 1 responses: '200': content: '*/*': {} description: default response summary: Cancel a query tags: - queries /datasets/{owner}/{id}/queries: get: description: 'List published saved queries associated with a dataset. Query definitions will be returned, not the query results. To retrieve query results use `GET:/queries/{id}/results`.' operationId: getPublishedDatasetQueries parameters: - in: path name: owner required: true schema: type: string - in: path name: id required: true schema: type: string - description: Number of results to return in: query name: limit schema: type: integer format: int32 default: 10 maximum: 100 minimum: 1 - description: A token supplied by the previous response to retrieve the next page of results in: query name: next schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedQueryResults' description: default response summary: List published queries tags: - queries post: description: Create a saved query in a specified dataset. operationId: createSavedQuery parameters: - in: path name: owner required: true schema: type: string minLength: 1 - in: path name: id required: true schema: type: string minLength: 1 requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateQueryRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/QuerySummaryResponse' description: default response summary: Create a saved query in a specified dataset tags: - queries /datasets/{owner}/{id}/queries/{queryId}: delete: description: Delete a saved query in a specified dataset. operationId: deleteSavedQuery parameters: - in: path name: owner required: true schema: type: string minLength: 1 - in: path name: id required: true schema: type: string minLength: 1 - in: path name: queryId required: true schema: type: string format: uuid responses: '200': content: application/json: schema: $ref: '#/components/schemas/SuccessMessage' description: default response summary: Delete a saved query in a specified dataset tags: - queries put: description: Update a saved query in a specified dataset. operationId: updateSavedQuery parameters: - in: path name: owner required: true schema: type: string minLength: 1 - in: path name: id required: true schema: type: string minLength: 1 - in: path name: queryId required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/QueryPutRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/QuerySummaryResponse' description: default response summary: Update a saved query in a specified dataset tags: - queries /datasets/{owner}/{id}/userQueries: get: description: 'List user saved queries associated with a dataset. Query definitions will be returned, not the query results. To retrieve query results use `GET:/queries/{id}/results`.' operationId: getUserSavedDatasetQueries parameters: - in: path name: owner required: true schema: type: string - in: path name: id required: true schema: type: string - description: Number of results to return in: query name: limit schema: type: integer format: int32 default: 10 maximum: 100 minimum: 1 - description: A token supplied by the previous response to retrieve the next page of results in: query name: next schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedQueryResults' description: default response summary: List user saved queries tags: - queries /projects/{owner}/{id}/queries: get: description: List published saved queries associated with a project. operationId: getProjectQueries parameters: - in: path name: owner required: true schema: type: string - in: path name: id required: true schema: type: string - description: Number of results to return in: query name: limit schema: type: integer format: int32 default: 10 maximum: 100 minimum: 1 - description: A token supplied by the previous response to retrieve the next page of results in: query name: next schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedQueryResults' description: default response summary: List published queries tags: - queries post: description: Create a saved query in a specified project. operationId: createSavedQuery_1 parameters: - in: path name: owner required: true schema: type: string minLength: 1 - in: path name: id required: true schema: type: string minLength: 1 requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateQueryRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/QuerySummaryResponse' description: default response summary: Create a saved query tags: - queries /projects/{owner}/{id}/queries/{queryId}: delete: description: Delete a saved query in a specified project. operationId: deleteSavedQuery_1 parameters: - in: path name: owner required: true schema: type: string minLength: 1 - in: path name: id required: true schema: type: string minLength: 1 - in: path name: queryId required: true schema: type: string format: uuid responses: '200': content: application/json: schema: $ref: '#/components/schemas/SuccessMessage' description: default response summary: Delete a saved query tags: - queries put: description: Update a saved query in a specified project. operationId: updateSavedQuery_1 parameters: - in: path name: owner required: true schema: type: string minLength: 1 - in: path name: id required: true schema: type: string minLength: 1 - in: path name: queryId required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/QueryPutRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/QuerySummaryResponse' description: default response summary: Update a saved query tags: - queries /projects/{owner}/{id}/userQueries: get: description: List user saved queries associated with a project. operationId: getUserSavedProjectQueries parameters: - in: path name: owner required: true schema: type: string - in: path name: id required: true schema: type: string - description: Number of results to return in: query name: limit schema: type: integer format: int32 default: 10 maximum: 100 minimum: 1 - description: A token supplied by the previous response to retrieve the next page of results in: query name: next schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedQueryResults' description: default response summary: List saved queries tags: - queries /queries/{id}: get: description: 'Retrieve a saved query. Query definitions will be returned, not query results. To retrieve query results use `GET:/queries/{id}/results`.' operationId: getQuery parameters: - in: path name: id required: true schema: type: string format: uuid responses: '200': content: application/json: schema: $ref: '#/components/schemas/QuerySummaryResponse' description: default response summary: Retrieve a saved query tags: - queries /queries/{id}/results: get: description: 'Execute a saved query. SQL results are available in a variety of formats. By default, `application/json` will be returned. Set the `Accept` header to one of the following values in accordance with your preference: * `text/csv` * `application/json` * `application/json-l` * `application/x-ndjson` SPARQL results are available in a variety of formats. By default, `application/sparql-results+json` will be returned. Set the `Accept` header to one of the following values in accordance with your preference: - `application/sparql-results+xml` - `application/sparql-results+json` - `application/rdf+json` - `application/rdf+xml` - `text/csv` - `text/tab-separated-values` - `text/turtle`' operationId: executeQuery parameters: - in: path name: id required: true schema: type: string format: uuid - in: query name: includeTableSchema schema: type: boolean default: false - description: Query token to use with cancel in: query name: queryruntoken schema: type: string responses: '200': content: application/json: {} application/json-l: {} application/rdf+json: {} application/rdf+xml: {} application/sparql-results+json: {} application/sparql-results+xml: {} application/trig: {} application/x-ndjson: {} text/csv: {} text/tab-separated-values: {} text/turtle: {} description: default response summary: Execute a saved query tags: - queries post: description: 'Execute a saved query (same as GET:/queries/{id}/results) with the option to specify named query parameters.' operationId: executeQueryWithPost parameters: - in: path name: id required: true schema: type: string format: uuid - description: Query token to use with cancel in: query name: queryruntoken schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SavedQueryExecutionRequest' responses: '200': content: application/json: {} application/json-l: {} application/rdf+json: {} application/rdf+xml: {} application/sparql-results+json: {} application/sparql-results+xml: {} application/trig: {} application/x-ndjson: {} text/csv: {} text/tab-separated-values: {} text/turtle: {} description: default response summary: Execute a saved query (with parameters) tags: - queries /queries/{id}/v/{versionId}: get: description: Retrieve a version of a saved query. Query definitions will be returned, not query results. operationId: getQueryVersion parameters: - in: path name: id required: true schema: type: string format: uuid - in: path name: versionId required: true schema: type: string format: uuid responses: '200': content: application/json: schema: $ref: '#/components/schemas/QuerySummaryResponse' description: default response summary: Retrieve a saved query version tags: - queries /sparql/{owner}: get: description: 'Execute a SPARQL query. The query will default to using the :current graph if the query contains no FROM clauses and no default graph URI parameters are specified, in which case it will return a 404 if the :current graph does not exist for the org. SPARQL results are available in a variety of formats. By default, `application/sparql-results+json` will be returned. Set the `Accept` header to one of the following values in accordance with your preference and the type of the query (SELECT, CONSTRUCT, DESCRIBE, ASK): - `application/sparql-results+xml` - `application/sparql-results+json` - `application/rdf+json` - `application/rdf+xml` - `text/csv` - `text/tab-separated-values` - `text/turtle` New to SPARQL? Check out data.world''s [SPARQL tutorial](https://docs.data.world/tutorials/sparql/).' operationId: queryViaGetWithDefaultGraph parameters: - in: path name: owner required: true schema: type: string - in: query name: query required: true schema: type: string minLength: 1 - in: query name: diagnose schema: type: boolean default: false - description: Specify URI for named graph(s) to query, overriding any FROM clauses in the query. If the default-graph-uri parameter is omitted and there are no FROM clauses, the :current graph will be used. See [Our Docs](https://docs.data.world/en/168180-understanding-the-catalog-graph.html#UUID-46e644b5-119a-a4a2-eb69-e09ce33bd986) for more info. in: query name: default-graph-uri schema: type: array items: type: string - description: Specify URI for named graph(s) to query, overriding any FROM NAMED clauses in the query. See [Our Docs](https://docs.data.world/en/168180-understanding-the-catalog-graph.html#UUID-46e644b5-119a-a4a2-eb69-e09ce33bd986) for more info. in: query name: named-graph-uri schema: type: array items: type: string - description: Query token to use with cancel in: query name: queryruntoken schema: type: string responses: '200': content: application/rdf+json: {} application/rdf+xml: {} application/sparql-results+json: {} application/sparql-results+xml: {} text/csv: {} text/tab-separated-values: {} text/turtle: {} description: default response summary: Execute SPARQL query via GET with the default graph tags: - queries post: description: 'Execute a SPARQL query. The query will default to using the :current graph if the query contains no FROM clauses and no default graph URI parameters are specified, in which case it will return a 404 if the :current graph does not exist for the org. SPARQL results are available in a variety of formats. By default, `application/sparql-results+json` will be returned. Set the `Accept` header to one of the following values in accordance with your preference and the type of the query (SELECT, CONSTRUCT, DESCRIBE, ASK): - `application/sparql-results+xml` - `application/sparql-results+json` - `application/rdf+json` - `application/rdf+xml` - `text/csv` - `text/tab-separated-values` - `text/turtle` New to SPARQL? Check out data.world''s [SPARQL tutorial](https://docs.data.world/tutorials/sparql/).' operationId: queryWithJsonRequestWithDefaultGraph parameters: - in: path name: owner required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SparqlQueryRequest' required: true responses: '200': content: application/rdf+json: {} application/rdf+xml: {} application/sparql-results+json: {} application/sparql-results+xml: {} text/csv: {} text/tab-separated-values: {} text/turtle: {} description: default response summary: Execute SPARQL query via POST with the default graph tags: - queries /sparql/{owner}/{id}: get: description: 'Execute a SPARQL query against a dataset or data project. SPARQL results are available in a variety of formats. By default, `application/sparql-results+json` will be returned. Set the `Accept` header to one of the following values in accordance with your preference and the type of the query (SELECT, CONSTRUCT, DESCRIBE, ASK): - `application/sparql-results+xml` - `application/sparql-results+json` - `application/rdf+json` - `application/rdf+xml` - `text/csv` - `text/tab-separated-values` - `text/turtle` New to SPARQL? Check out data.world''s [SPARQL tutorial](https://docs.data.world/tutorials/sparql/).' operationId: queryViaGet parameters: - in: path name: owner required: true schema: type: string - description: Dataset to query, e.g. `ddw-catalogs` in: path name: id required: true schema: type: string - in: query name: query required: true schema: type: string minLength: 1 - in: query name: diagnose schema: type: boolean default: false - description: Specify URI for named graph(s) to query, overriding any FROM clauses in the query. See [Our Docs](https://docs.data.world/en/168180-understanding-the-catalog-graph.html#UUID-46e644b5-119a-a4a2-eb69-e09ce33bd986) for more info. in: query name: default-graph-uri schema: type: array items: type: string - description: Specify URI for named graph(s) to query, overriding any FROM NAMED clauses in the query. See [Our Docs](https://docs.data.world/en/168180-understanding-the-catalog-graph.html#UUID-46e644b5-119a-a4a2-eb69-e09ce33bd986) for more info. in: query name: named-graph-uri schema: type: array items: type: string - description: Query token to use with cancel in: query name: queryruntoken schema: type: string responses: '200': content: application/rdf+json: {} application/rdf+xml: {} application/sparql-results+json: {} application/sparql-results+xml: {} text/csv: {} text/tab-separated-values: {} text/turtle: {} description: default response summary: Execute SPARQL query via GET tags: - queries post: description: 'Execute a SPARQL query against a dataset or data project. SPARQL results are available in a variety of formats. By default, `application/sparql-results+json` will be returned. Set the `Accept` header to one of the following values in accordance with your preference and the type of the query (SELECT, CONSTRUCT, DESCRIBE, ASK): - `application/sparql-results+xml` - `application/sparql-results+json` - `application/rdf+json` - `application/rdf+xml` - `text/csv` - `text/tab-separated-values` - `text/turtle` New to SPARQL? Check out data.world''s [SPARQL tutorial](https://docs.data.world/tutorials/sparql/).' operationId: queryWithJsonRequest parameters: - in: path name: owner required: true schema: type: string - description: Dataset to query, e.g. `ddw-catalogs` in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SparqlQueryRequest' required: true responses: '200': content: application/rdf+json: {} application/rdf+xml: {} application/sparql-results+json: {} application/sparql-results+xml: {} text/csv: {} text/tab-separated-values: {} text/turtle: {} description: default response summary: Execute SPARQL query via POST tags: - queries /sql/{owner}/{id}: get: description: Same as `POST:/sql/{owner}/{id}` operationId: sqlGet parameters: - in: path name: owner required: true schema: type: string - in: path name: id required: true schema: type: string - in: query name: includeTableSchema schema: type: boolean default: false - in: query name: query required: true schema: type: string minLength: 1 - in: query name: dialect schema: type: string default: DW_SQL enum: - DW_SQL - POSTGRESQL - in: query name: diagnose schema: type: boolean default: false - description: Query token to use with cancel in: query name: queryruntoken schema: type: string responses: '200': content: application/json: {} application/json-l: {} application/x-ndjson: {} text/csv: {} description: default response summary: SQL query (via GET) tags: - queries post: description: 'Execute a SQL query against a dataset or data project. SQL results are available in a variety of formats. By default, `application/json` will be returned. Set the `Accept` header to one of the following values in accordance with your preference: * `text/csv` * `application/json` * `application/json-l` * `application/x-ndjson` New to SQL? Check out data.world''s [SQL manual](https://docs.data.world/tutorials/dwsql/) .' operationId: sqlPostWithJsonRequest parameters: - in: path name: owner required: true schema: type: string - in: path name: id required: true schema: type: string - in: query name: dialect schema: type: string default: DW_SQL enum: - DW_SQL - POSTGRESQL - in: query name: diagnose schema: type: boolean default: false requestBody: content: application/json: schema: $ref: '#/components/schemas/SqlQueryRequest' required: true responses: '200': content: application/json: {} application/json-l: {} application/x-ndjson: {} text/csv: {} description: default response summary: SQL query tags: - queries /sql/{owner}/{id}/describe: post: description: 'This endpoint describes what columns will be included if the given SQL query is performed against the specified dataset. New to SQL? Check out data.world''s [SQL manual](https://docs.data.world/tutorials/dwsql/) .' operationId: sqlDescribe parameters: - in: path name: owner required: true schema: type: string - in: path name: id required: true schema: type: string - in: query name: dialect schema: type: string default: DW_SQL enum: - DW_SQL - POSTGRESQL requestBody: content: application/json: schema: $ref: '#/components/schemas/SqlQueryRequest' required: true responses: '200': content: application/json: {} application/json-l: {} application/x-ndjson: {} text/csv: {} description: default response summary: Describe a SQL query tags: - queries components: schemas: SavedQueryExecutionRequest: type: object properties: datasetVersions: type: string defaultGraphUris: type: array items: type: string includeTableSchema: type: boolean maxRows: type: integer format: int64 namedGraphUris: type: array items: type: string parameters: type: object additionalProperties: $ref: '#/components/schemas/RdfTerm' queryRunToken: type: string QueryPutRequest: type: object properties: content: type: string description: type: string maxLength: 1000 minLength: 0 name: type: string maxLength: 128 minLength: 0 published: type: boolean required: - content - name CreateQueryRequest: type: object properties: content: type: string description: type: string maxLength: 1000 minLength: 0 language: type: string enum: - SPARQL - SQL name: type: string maxLength: 128 minLength: 0 published: type: boolean required: - content - language - name SparqlQueryRequest: type: object properties: datasetVersions: type: string defaultGraphUris: type: array items: type: string diagnose: type: boolean namedGraphUris: type: array items: type: string query: type: string queryRunToken: type: string required: - query PaginatedQueryResults: type: object properties: count: type: integer format: int32 minimum: 0 nextPageToken: type: string records: type: array items: $ref: '#/components/schemas/QuerySummaryResponse' required: - count - records QuerySummaryResponse: type: object properties: body: type: string created: type: string format: date-time description: type: string id: type: string format: uuid language: type: string enum: - SPARQL - SQL name: type: string owner: type: string parameters: type: object additionalProperties: $ref: '#/components/schemas/QueryParameter' updated: type: string format: date-time version: type: string RdfTerm: type: object properties: datatype: type: string type: type: string enum: - literal - uri - bnode value: type: string xml:lang: type: string required: - type - value QueryParameter: type: object properties: datatype: type: string type: type: string SuccessMessage: type: object properties: message: type: string maxLength: 256 minLength: 0 SqlQueryRequest: type: object properties: datasetVersions: type: string includeTableSchema: type: boolean query: type: string queryRunToken: type: string required: - query securitySchemes: bearerAuth: bearerFormat: JWT scheme: bearer type: http