File-based connections schema

service.db.files.graphqls

This API is available in Enterprise and AWS editions only.

To authenticate API requests, you’ll need an API token. Learn how to generate an access token.

See usage examples in the cloudbeaver-graphql-examples repository.

You can try queries in the built-in GraphQL console, available on your server at https://your-server-address/api/gql/console. This tool lets you test requests directly from your browser.

For a live example, see the demo GraphQL console.

API Endpoints
https://your-server-address/api/gql

Queries

_types

Description

This schema currently exposes only mutations.

Response

Returns [_PageTypes]

Example

Query
query _types {
  _types {
    ... on FileBasedConnectionInfo {
      ...FileBasedConnectionInfoFragment
    }
  }
}
Response
{"data": {"_types": [FileBasedConnectionInfo]}}

Mutations

createConnectionFromCloudStorageFile

Description

Creates new custom connection from a cloud storage file

Response

Returns a FileBasedConnectionInfo!

Arguments
Name Description
objectId - String!
projectId - String!

Example

Query
mutation createConnectionFromCloudStorageFile(
  $objectId: String!,
  $projectId: String!
) {
  createConnectionFromCloudStorageFile(
    objectId: $objectId,
    projectId: $projectId
  ) {
    connectionInfo {
      ...ConnectionInfoFragment
    }
    nodePathToOpen
  }
}
Variables
{"objectId": "<string>", "projectId": "<string>"}
Response
{
  "data": {
    "createConnectionFromCloudStorageFile": {
      "connectionInfo": ConnectionInfo,
      "nodePathToOpen": "<string>"
    }
  }
}

Types

Boolean

Description

The Boolean scalar type represents true or false.

Example
"<boolean>"
Types

Condition

Description

Represents a dynamic condition for a property, such as visibility or read-only state

Fields
Field Name Description
expression - String! The logical expression that defines when the condition applies
conditionType - ConditionType! The type of condition (e.g., HIDE or READ_ONLY)
Example
{"expression": "<string>", "conditionType": "HIDE"}
Types

ConditionType

Values
Enum Value Description

HIDE

 hiding property condition

READ_ONLY

 restriction for setting a property value
Example
"HIDE"
Types

ConnectionInfo

Description

Connection instance

Fields
Field Name Description
id - ID! Connection unique ID
driverId - ID! ID of the driver that is used for this connection (see DriverInfo)
name - String! Connection name
description - String Connection description
host - String
port - String
serverName - String
databaseName - String
url - String
mainPropertyValues - Object Main connection properties. Contains host, port, database, server name fields
expertSettingsValues - Object Expert connection settings. Contains expert settings properties (like keep-alive interval or auto-commit) that are not often used
keepAliveInterval - Int! Connection keep-alive interval in seconds
autocommit - Boolean Defines if the connection is in auto-commit mode
properties - Object
connected - Boolean! Indicates if the connection is already connected to the database
provided - Boolean!
readOnly - Boolean! Indicates if the connection is read-only (no data modification allowed)
useUrl - Boolean! Forces connection URL use, host/port/database parameters will be ignored
saveCredentials - Boolean! Forces credentials save. This flag doesn't work in shared projects.
sharedCredentials - Boolean! Shared credentials - the same for all users, stored in secure storage.
sharedSecrets - [SecretInfo!]!
credentialsSaved - Boolean! Determines that credentials were saved for current user. This field read is slow, it should be read only when it really needed
authNeeded - Boolean! Determines that additional credentials are needed to connect This field read is slow, it should be read only when it really needed
folder - ID ID of the connection folder where this connection is stored
nodePath - String Node path of the connection in the navigator
connectTime - String Connection time in ISO format
connectionError - ServerError Connection error if any
serverVersion - String Server version that is used for this connection
clientVersion - String Client version that is used for this connection
origin - ObjectOrigin!
authModel - ID ID of the auth model that is used for this connection (see authModels)
authProperties - [ObjectPropertyInfo!]!
providerProperties - Object!
networkHandlersConfig - [NetworkHandlerConfig!]!
features - [String!]! Supported features (provided etc)
navigatorSettings - NavigatorSettings! Navigator settings for the connection (with user settings applied)
defaultNavigatorSettings - NavigatorSettings! Default navigator settings for the connection (without user settings applied)
supportedDataFormats - [ResultDataFormat!]!
configurationType - DriverConfigurationType
canViewSettings - Boolean! Access properties
canEdit - Boolean!
canDelete - Boolean!
projectId - ID!
requiredAuth - String
defaultCatalogName - String
defaultSchemaName - String
defaultUserPreferences - Object Default user settings for connection
tools - [String!]! List of tools that can be used with this connection. Returns empty list if no tools are available
connectionType - ID!
driverConfiguration - DriverConfiguration! Driver configuration
Example
{
  "id": "<id>",
  "driverId": "<id>",
  "name": "<string>",
  "description": "<string>",
  "host": "<string>",
  "port": "<string>",
  "serverName": "<string>",
  "databaseName": "<string>",
  "url": "<string>",
  "mainPropertyValues": "<object>",
  "expertSettingsValues": "<object>",
  "keepAliveInterval": "<int>",
  "autocommit": "<boolean>",
  "properties": "<object>",
  "connected": "<boolean>",
  "provided": "<boolean>",
  "readOnly": "<boolean>",
  "useUrl": "<boolean>",
  "saveCredentials": "<boolean>",
  "sharedCredentials": "<boolean>",
  "sharedSecrets": [SecretInfo],
  "credentialsSaved": "<boolean>",
  "authNeeded": "<boolean>",
  "folder": "<id>",
  "nodePath": "<string>",
  "connectTime": "<string>",
  "connectionError": ServerError,
  "serverVersion": "<string>",
  "clientVersion": "<string>",
  "origin": ObjectOrigin,
  "authModel": "<id>",
  "authProperties": [ObjectPropertyInfo],
  "providerProperties": "<object>",
  "networkHandlersConfig": [NetworkHandlerConfig],
  "features": ["<string>"],
  "navigatorSettings": NavigatorSettings,
  "defaultNavigatorSettings": NavigatorSettings,
  "supportedDataFormats": ["resultset"],
  "configurationType": "MANUAL",
  "canViewSettings": "<boolean>",
  "canEdit": "<boolean>",
  "canDelete": "<boolean>",
  "projectId": "<id>",
  "requiredAuth": "<string>",
  "defaultCatalogName": "<string>",
  "defaultSchemaName": "<string>",
  "defaultUserPreferences": "<object>",
  "tools": ["<string>"],
  "connectionType": "<id>",
  "driverConfiguration": DriverConfiguration
}
Types

DictionaryValueInfo

Description

Generic dictionary value: an identifier with a human readable name and an optional description

Fields
Field Name Description
id - ID! Value ID
name - String! Human readable value name
description - String Value description
Example
{"id": "<id>", "name": "<string>", "description": "<string>"}
Types

DriverConfiguration

Description

Database-dependent metadata describing features supported by the driver

Fields
Field Name Description
supportedInsertReplaceMethods - [DictionaryValueInfo!]! Supported 'on duplicate key' replace methods for this connection's SQL dialect
supportsBulkLoad - Boolean! Whether the connection's database supports bulk load during data import
supportsTransactions - Boolean! Whether the connection's database supports transactions
Example
{
  "supportedInsertReplaceMethods": [DictionaryValueInfo],
  "supportsBulkLoad": "<boolean>",
  "supportsTransactions": "<boolean>"
}
Types

DriverConfigurationType

Values
Enum Value Description

MANUAL

 Driver uses host, port, database and server name fields

URL

 Driver uses URL field
Example
"MANUAL"
Types

FileBasedConnectionInfo

Description

Information about a connection created from a file-based source

Fields
Field Name Description
connectionInfo - ConnectionInfo! Connection details
nodePathToOpen - String! Path to the node that should be opened after connection creation
Example
{
  "connectionInfo": ConnectionInfo,
  "nodePathToOpen": "<string>"
}
Types

ID

Description

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Example
"<id>"
Types

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example
"<int>"
Types

NavigatorSettings

Fields
Field Name Description
showSystemObjects - Boolean!
showUtilityObjects - Boolean!
showOnlyEntities - Boolean!
mergeEntities - Boolean!
hideFolders - Boolean!
hideSchemas - Boolean!
hideVirtualModel - Boolean!
userSettings - Boolean! Shows whether these settings are user-specific or global
Example
{
  "showSystemObjects": "<boolean>",
  "showUtilityObjects": "<boolean>",
  "showOnlyEntities": "<boolean>",
  "mergeEntities": "<boolean>",
  "hideFolders": "<boolean>",
  "hideSchemas": "<boolean>",
  "hideVirtualModel": "<boolean>",
  "userSettings": "<boolean>"
}
Types

NetworkHandlerAuthType

Description

SSH network handler authentication type

Values
Enum Value Description

PASSWORD

PUBLIC_KEY

AGENT
Example
"PASSWORD"
Types

NetworkHandlerConfig

Description

SSH/SSL network handler config. Name without prefix only for backward compatibility

Fields
Field Name Description
id - ID!
enabled - Boolean! Defines if the network handler is enabled
authType - NetworkHandlerAuthType! SSH network handler auth type use properties
userName - String SSH network handler user name
password - String SSH network handler user password
key - String SSH network handler private key use secured properties
savePassword - Boolean! A flag that indicates if the password should be saved in the secure storage
properties - Object! Network handler properties (name/value)
secureProperties - Object! Network handler secure properties (name/value). Used for passwords and keys
Example
{
  "id": "<id>",
  "enabled": "<boolean>",
  "authType": "PASSWORD",
  "userName": "<string>",
  "password": "<string>",
  "key": "<string>",
  "savePassword": "<boolean>",
  "properties": "<object>",
  "secureProperties": "<object>"
}
Types

Object

Description

Any object (JSON)

Example
"<object>"
Types

ObjectOrigin

Fields
Field Name Description
type - ID!
subType - ID
displayName - String!
icon - String
configuration - Object
details - [ObjectPropertyInfo!]
Example
{
  "type": "<id>",
  "subType": "<id>",
  "displayName": "<string>",
  "icon": "<string>",
  "configuration": "<object>",
  "details": [ObjectPropertyInfo]
}
Types

ObjectPropertyInfo

Description

Information about the object property used to generate its UI

Fields
Field Name Description
id - String Unique property identifier
displayName - String Human-readable name
description - String Property description
hint - String Usage hint for the property
category - String Property category (may be used if object has a lot of properties)
dataType - String Property data type (e.g., int, String)
value - Object Property value (can be resource-intensive for some properties, e.g., RowCount for tables)
validValues - [Object] List of allowed values (for enumerable properties)
defaultValue - Object Default property value
length - ObjectPropertyLength! Property value length
features - [String!]! List of supported features (e.g., system, hidden, inherited, foreign, expensive)
order - Int! Order position
supportedConfigurationTypes - [String!] Supported configuration types (for driver properties)
required - Boolean! Is the property required
scopes - [String!] List of preference scopes (e.g., global, user)
conditions - [Condition!] Dynamic conditions for the property (e.g., visibility or read-only)
Example
{
  "id": "<string>",
  "displayName": "<string>",
  "description": "<string>",
  "hint": "<string>",
  "category": "<string>",
  "dataType": "<string>",
  "value": "<object>",
  "validValues": ["<object>"],
  "defaultValue": "<object>",
  "length": "TINY",
  "features": ["<string>"],
  "order": "<int>",
  "supportedConfigurationTypes": ["<string>"],
  "required": "<boolean>",
  "scopes": ["<string>"],
  "conditions": [Condition]
}
Types

ObjectPropertyLength

Values
Enum Value Description

TINY

 1 character

SHORT

 20 characters

MEDIUM

 <= 64 characters

LONG

 Full line length. The default

MULTILINE

 Multi-line long text
Example
"TINY"
Types

ResultDataFormat

Values
Enum Value Description

resultset

document

graph

timeseries
Example
"resultset"
Types

SecretInfo

Fields
Field Name Description
displayName - String!
secretId - String!
Example
{"displayName": "<string>", "secretId": "<string>"}
Types

ServerError

Description

Various server errors descriptor

Fields
Field Name Description
message - String Error message text
errorCode - String Retrieves the vendor-specific error code
errorType - String Type/category of the error
stackTrace - String Stack trace for debugging
causedBy - ServerError Nested error that caused this error (recursive)
Example
{
  "message": "<string>",
  "errorCode": "<string>",
  "errorType": "<string>",
  "stackTrace": "<string>",
  "causedBy": ServerError
}
Types

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example
"<string>"
Types

_PageTypes

Types
Union Types

FileBasedConnectionInfo
Example
FileBasedConnectionInfo
Documentation by Anvil SpectaQL