openapi: 3.0.1
info:
  title: Stardog HTTP Checkpoints Virtual Graphs External Compute API
  description: "# Overview\nStardog supports the standard SPARQL Protocol HTTP bindings, as well as additional functionality via HTTP.\nStardog also supports SPARQL 1.1’s Service Description format. See the [spec](https://www.w3.org/TR/sparql11-service-description/) if you want details.\n### Generating URLs\nIf you are running the HTTP server at\n\n ```http://localhost:12345```\n\nTo form the URI of a particular Stardog Database, the Database Short Name is the first URL path segment appended to the deployment URI. For example, for the Database called `cytwombly`, deployed in the above example HTTP server, the Database Network Name might be\n\n```http://localhost:12345/cytwombly```\n\nAll the resources related to this database are identified by URL path segments relative to the Database Network Name; hence:\n\n```http://localhost:12345/cytwombly/size```\n# Error Codes\nHere are explanations of what the various error codes mean:\n\nError Code | Category | Meaning\n-----------|----------|---------\n000012 | GENERIC |UNKNOWN\n000IA2 | GENERIC |ILLEGAL_ARGUMENT\n000SD4 | GENERIC |SHUTTING_DOWN\n00PCE2 | GENERIC |PROCESS_CANCELLED\n00PE2 | GENERIC |PROCESS_EXISTS\n00PNE2 | GENERIC |PROCESS_NOT_FOUND\n00UOE2 | GENERIC |UNSUPPORTED_OPERATION\n0D0012 | DATABASE |UNKNOWN_DATABASE_EXCEPTION\n0D0CE3 | DATABASE |DATABASE_CONSISTENCY_EXCEPTION\n0D0DC2 | DATABASE |DATABASE_CONFLICT\n0D0DE2 | DATABASE |DATABASE_EXISTS\n0D0DU2 | DATABASE |DATABASE_UNKNOWN\n0D0TU2 | DATABASE |TRANSACTION_UNKNOWN\n0DICC2 | DATABASE |INVALID_CONFIGURATION\n0DIDN2 | DATABASE |INVALID_DATABASE_NAME\n0DIDS2 | DATABASE |INVALID_DATABASE_STATE\nCLNIC3 | CLUSTER_ERROR |NOT_IN_CLUSTER\nCLOEF3 | CLUSTER_ERROR |EXPEL_FAILED\nHS0012 | HTTP |UNKNOWN_CONNECTION_EXCEPTION\nHSJSE2 | HTTP |JSON_SYNTAX_EXCEPTION\nHSJSO2 | HTTP |JSON_EXCEPTION\nHSSSL3 | HTTP |SSL_EXCEPTION\nQE0012 | QUERY_EXECUTION |UNKNOWN_QUERY_EXCEPTION\nQE0FE2 | QUERY_EXECUTION |FUNCTION_EXISTS\nQE0PE2 | QUERY_EXECUTION |PARSE_EXCEPTION\nQE0QE2 | QUERY_EXECUTION |QUERY_EXISTS\nQECTP2 | QUERY_EXECUTION |CANNOT_TRANSLATE_PLAN\nQEFNF2 | QUERY_EXECUTION |FUNCTION_NOT_FOUND\nQEIQT2 | QUERY_EXECUTION |INVALID_QUERY_TYPE\nQEIVR2 | QUERY_EXECUTION |INVALID_RDF\nQEMAQ2 | QUERY_EXECUTION |MALFORMED_QUERY\nQEONS2 | QUERY_EXECUTION |OPERATION_NOT_SUPPORTED\nQEQNF2 | QUERY_EXECUTION |QUERY_NOT_FOUND\nQEQOE2 | QUERY_EXECUTION |OPERATOR_EXCEPTION\nQEQPE2 | QUERY_EXECUTION |QUERY_PARSE_EXCEPTION\nQEWCE2 | QUERY_EXECUTION |WRITE_CONFLICT_EXCEPTION\nSE0012 | SECURITY |UNKNOWN_SECURITY_EXCEPTION\nSE0IP2 | SECURITY |ILLEGAL_PASSWORD\nSE0RE2 | SECURITY |SECURITY_RESOURCE_EXISTS\nSEAEE2 | SECURITY |AUTHENTICATION_EXCEPTION\nSEAOE2 | SECURITY |AUTHORIZATION_EXCEPTION\nSEIPT2 | SECURITY |INCORRECT_PRINCIPAL_TRANSACTION\nSERIU2 | SECURITY |SECURITY_RESOURCE_IN_USE\nSERNF2 | SECURITY |SECURITY_RESOURCE_NOT_FOUND\nSERNI2 | SECURITY |SECURITY_RESOURCE_NAME_INVALID\nSERTI2 | SECURITY |SECURITY_RESOURCE_TYPE_INVALID\nZK0013 | ZOOKEEPER_ERROR |ZOOKEEPER_UNKNOWN_EXCEPTION\nZK00U3 | ZOOKEEPER_ERROR |UNIMPLEMENTED\nZK0AE3 | ZOOKEEPER_ERROR |API_ERROR\nZK0AF3 | ZOOKEEPER_ERROR |AUTH_FAILED\nZK0BV3 | ZOOKEEPER_ERROR |BAD_VERSION\nZK0CE3 | ZOOKEEPER_ERROR |NO_CHILDREN_FOR_EPHEMERAL\nZK0CL3 | ZOOKEEPER_ERROR |CONNECTION_LOSS\nZK0CR3 | ZOOKEEPER_ERROR |ZOOKEEPER_CONNECTION_REFUSED\nZK0DI3 | ZOOKEEPER_ERROR |DATA_INCONSISTENCY\nZK0IA3 | ZOOKEEPER_ERROR |BAD_ARGUMENTS\nZK0ME3 | ZOOKEEPER_ERROR |MARSHALLING_ERROR\nZK0NA3 | ZOOKEEPER_ERROR |NO_AUTH\nZK0NE3 | ZOOKEEPER_ERROR |NODE_EXISTS\nZK0NN3 | ZOOKEEPER_ERROR |NO_NODE\nZK0OT3 | ZOOKEEPER_ERROR |OPERATION_TIMEOUT\nZK0RI3 | ZOOKEEPER_ERROR |RUNTIME_INCONSISTENCY\nZK0SE3 | ZOOKEEPER_ERROR |SYSTEM_ERROR\nZK0SM3 | ZOOKEEPER_ERROR |SESSION_MOVED\nZKEXS3 | ZOOKEEPER_ERROR |SESSION_EXPIRED\nZKIAL3 | ZOOKEEPER_ERROR |INVALIDACL\nZKICB3 | ZOOKEEPER_ERROR |INVALID_CALLBACK\nZKNEY3 | ZOOKEEPER_ERROR |NOT_EMPTY\nZKNRO3 | ZOOKEEPER_ERROR |NOT_READONLY\n"
  contact:
    url: https://stardog.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  version: 12.0.3
  x-logo:
    url: https://d33wubrfki0l68.cloudfront.net/66e9dcff51317cfc11b9f3d4ce2917a11ba81681/543c1/img/stardog-logo-optimized.svg
servers:
- url: http://localhost:5820
tags:
- name: Virtual Graphs External Compute
  description: Operations for virtualizing structured data on external compute engines
paths:
  /admin/virtual_graphs_compute/import:
    post:
      tags:
      - Virtual Graphs External Compute
      summary: Import virtual graph
      description: Import (materialize) a delimited file into the knowledge graph
      operationId: importFileExternal
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VIRTUAL_GRAPH_IMPORT_FILE'
        required: true
      responses:
        '204':
          description: File imported
  /admin/virtual_graphs_compute/import_db:
    post:
      tags:
      - Virtual Graphs External Compute
      summary: Import virtual graph
      description: Import (materialize) a virtual graph directly into the local knowledge graph
      operationId: importDbExternal
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VIRTUAL_GRAPH_IMPORT'
        required: true
      responses:
        '204':
          description: Virtual graph imported
components:
  schemas:
    IMPORT_FILE_OPTIONS:
      properties:
        csv.separator:
          type: string
          description: For CSV import, a single-character separator
          default: ','
        csv.quote:
          type: string
          description: For CSV import, a single character used to encapsulate values containing special characters
          default: '"'
        csv.header:
          type: boolean
          description: For CSV import, should the import process read the header row?
          default: true
        csv.skip.empty:
          type: boolean
          description: For CSV import, should empty values be skipped?
          default: true
        csv.class:
          type: string
          description: For CSV import, which class should imported rows be members of?
        csv.hash.function:
          type: string
          description: 'For CSV import, which hash function should be used when the # notation is used?'
          default: SHA1
        unique.key.sets:
          type: string
          description: 'For data sources that do not express unique constraints in their metadata, either because unique constraints are not supported or because the data source did not include some or all of the valid constraints for reasons such as performance concerns, this property is used to define additional constraints manually. The property value is a comma-separated list of keys that define unique rows in a table. Each key is itself a comma-separated list of schema-qualified columns, enclosed in parentheses. For example, if table `APP.CUSTOMERS` has an `ID` column that serves as a primary key and a pair of columns, `FNAME` and `LNAME`, that together are a unique key, the value to express that is: `(APP.CUSTOMERS.ID),(APP.CUSTOMERS.FNAME,APP.CUSTOMERS.LNAME)`'
      externalDocs:
        url: https://docs.stardog.com/virtual-graphs/virtual-graph-configuration#virtual-graph-properties
    VIRTUAL_GRAPH_IMPORT_FILE:
      required:
      - database
      - mappings
      - options
      - input_file_type
      - input_file
      properties:
        database:
          type: string
          description: The database into which to import the file
        mappings:
          type: string
        options:
          $ref: '#/components/schemas/IMPORT_FILE_OPTIONS'
        named_graph:
          type: string
          format: URI
        input_file_type:
          type: string
          enum:
          - JSON
          - DELIMITED
        input_file:
          type: string
    VIRTUAL_GRAPH_OPTIONS:
      properties:
        base:
          type: string
          description: Base IRI used to resolve relative IRIs from virtual graphs
          format: URI
        jdbc.url:
          type: string
          description: The URL of the JDBC connection
        jdbc.username:
          type: string
          description: The username used to make the JDBC connection
        jdbc.password:
          type: string
          description: The password used to make the JDBC connection
        jdbc.driver:
          type: string
          description: The driver class name used to make the JDBC connection. If omitted, driver will be taken from registered Service Providers.
        jdbc.statement.fetch.size:
          type: integer
          description: A hint as to the number of rows that should be fetched from the database at a time. Used to balance network traffic with memory use.
          format: int32
          example: 42
        mappings.syntax:
          type: string
          enum:
          - R2RML
          - SMS
        mappings.format:
          type: string
          description: For R2RML, the RDF format of the mappings
        mongodb.uri:
          type: string
          description: The URI for a MongoDB connection
        elasticsearch.rest.urls:
          type: string
          description: Whitespace-delimited list of connection `scheme://host:port` values for Elasticsearch. Scheme defaults to `http`.
          example: https://server1:9200 http://server2:9200 server3:9200
        elasticsearch.indexes:
          type: string
          description: Optional comma-delimited list of indexes to make visible to the data source. Defaults to all indexes.
          example: my_index1,other_index
        elasticsearch.username:
          type: string
        elasticsearch.password:
          type: string
        cassandra.contact.point:
          type: string
          description: The address of the Cassandra node(s) that the driver uses to discover the cluster topology
        cassandra.port:
          type: integer
          description: The port to use to connect to the Cassandra host.
          format: int32
          example: 42
          default: 9042
        cassandra.keyspace:
          type: string
          description: The Cassandra keyspace to use for this session
        cassandra.username:
          type: string
          description: The username for the Cassandra cluster
        cassandra.password:
          type: string
          description: The password for the Cassandra cluster
        cassandra.allow.filtering:
          type: boolean
          description: Whether to include the `ALLOW FILTERING` clause at the end of Cassandra CQL queries. Not recommended for production use.
          default: false
        sparql.url:
          type: string
          description: SPARQL query endpoint/connection string with database specified
          format: URI
          example: http://myhost:26023/testdb/query
        sparql.username:
          type: string
          description: The username to access the SPARQL endpoint
        sparql.password:
          type: string
          description: The password to access the SPARQL endpoint
        sparql.graphname:
          type: string
          description: The graph name on the SPARQL endpoint to be mapped as virtual graph
        sparql.statsbasedoptimization:
          type: boolean
          description: Whether to enable statistics-based optimization while accessing the SPARQL endpoint
          default: true
        parser.sql.quoting:
          type: string
          description: DB quoting convention used by the parser
          example: ANSI
        sql.functions:
          type: string
          description: A comma-separated list of SQL function names to register with the parser
        percent.encode:
          type: boolean
          description: Should IRI template strings be percent-encoded to be valid IRIs?
          default: true
        unique.key.sets:
          type: string
          description: 'For data sources that do not express unique constraints in their metadata, either because unique constraints are not supported or because the data source did not include some or all of the valid constraints for reasons such as performance concerns, this property is used to define additional constraints manually. The property value is a comma-separated list of keys that define unique rows in a table. Each key is itself a comma-separated list of schema-qualified columns, enclosed in parentheses. For example, if table `APP.CUSTOMERS` has an `ID` column that serves as a primary key and a pair of columns, `FNAME` and `LNAME`, that together are a unique key, the value to express that is: `(APP.CUSTOMERS.ID),(APP.CUSTOMERS.FNAME,APP.CUSTOMERS.LNAME)`'
        sql.dialect:
          type: string
          description: The format of the generated SQL, for use when using an unsupported JDBC driver
          example: MYSQL
        sql.schemas:
          type: string
          description: A comma-separated list of schemas to append to the schema search path
        sql.default.schema:
          type: string
          description: Override the default schema for the connected user
        default.mapping.include.tables:
          type: string
          description: A comma-separated list of tables to include when generating default mappings. Incompatible with `default.mapping.exclude.tables`
        default.mapping.exclude.tables:
          type: string
          description: A comma-separated list of tables to exclude when generating default mappings. Incompatible with `default.mapping.include.tables`
        schema.in.generated.mappings:
          type: boolean
          description: Whether to include the name of the schema (along with the table name) in the templates for IRIs when automatically generating mappings
        union.strategy:
          type: string
          description: Strategy for translating SPARQL UNION to SQL. For use when using an unsupported JDBC driver.
          enum:
          - COALESCED
          - EMBEDDED
        charset.handling:
          type: boolean
          description: Whether to prefix SQL NVARCHAR string literals with N. The default is dialect-dependent. For use when using an unsupported JDBC driver.
      additionalProperties:
        pattern: ext\..+
        type: string
        description: Additional properties to pass directly to the JDBC driver
      externalDocs:
        url: https://docs.stardog.com/virtual-graphs/virtual-graph-configuration#virtual-graph-properties
    VIRTUAL_GRAPH_IMPORT:
      required:
      - db
      - mappings
      - named_graph
      - remove_all
      - options
      properties:
        db:
          type: string
          description: The database into which to import the graph
        mappings:
          type: string
        data_source:
          type: string
        named_graph:
          type: string
        remove_all:
          type: boolean
          description: Should the target named graph be cleared before importing?
        options:
          $ref: '#/components/schemas/VIRTUAL_GRAPH_OPTIONS'
externalDocs:
  url: https://docs.stardog.com
x-tagGroups:
- name: Data Unification
  tags:
  - Data Sources
  - Virtual Graphs
- name: Virtual Graphs External Compute
  tags:
  - Virtual Graphs External Compute
- name: Server
  tags:
  - Monitoring
  - Stored Functions
  - Server Status/Metrics
  - Server Admin
  - Queries
  - Cluster Admin
- name: Database
  tags:
  - Checkpoints
  - DB Admin
  - Integrity Constraints / SHACL
  - Data Caching
  - Graph Store Protocol
  - Matcher, aligning schemas from various data sources
  - Reasoning
  - Transactions
  - GraphQL
  - SPARQL
  - EntityResolution
- name: Security
  tags:
  - Roles
  - Permissions
  - Users
- name: Knowledge Catalog
  tags:
  - Knowledge Catalog