Explore the sample with Kubling Studio
Kubling Studio is the embedded workspace for exploring, querying and operating a running Kubling instance. It is not a mutable data-source configuration wizard: providers and production VDB definitions remain version-controlled deployment artifacts.
This guide continues from the Quickstart sample. Its credentials, VDB and example data refer to that environment.
Embedded Studio is served from /console when ENABLE_WEB_CONSOLE is
enabled. Protect it with the same network, TLS and identity controls used for
the instance HTTP APIs.
Open the workspace
Sign in
In the Quickstart, open
http://localhost:8282/console and enter
quickstart as both username and password. The values only satisfy the local
login form; the sample VDB has no authentication delegate and does not persist
them.
In an authenticated deployment, Studio creates a session for the supplied Kubling account. Catalog visibility, queries and mutations use that account’s permissions; Studio does not provide a privileged path around VDB policies.
Select the Virtual Database
Choose ProviderQuickstartVDB. Studio loads its live catalog from Kubling and
shows the physical provider schema imported through the Provider gRPC
contract.
Inspect the catalog
Expand provider and inspect the PROJECT, TASK, AUDIT_EVENT and
TYPE_SAMPLE tables. Schema DDL inspection shows keys, types, mutability and
annotations reported by the provider.
Use SQL Workspace
SQL Workspace provides catalog-aware completion, query history, dynamic result grids and mutation feedback. Follow the Quickstart’s deterministic query and mutation to exercise both read and write paths against the In-memory provider.
Repeated output names v26.6+
SQL results preserve every selected value when two or more columns have the
same output name, including common joins such as source.id, target.id. Aliases
remain useful for readability, but Studio no longer requires them to avoid
losing a value in the result grid.
Semantics preview v26.5+
When the selected VDB has an active semantic package, the Semantics workspace lets you inspect the compiled result rather than reconstruct it from source files. It includes:
- package and activation overview
- entities, properties and identities
- relationships and executable bindings
- an interactive relationship graph
- diagnostics and the normalized JSON document
The workspace is read-only. Provider fragments, authored modules and VDB composition remain version-controlled deployment artifacts.
Read the workspace
| View | What it answers |
|---|---|
| Overview | Is the package active, which query surfaces are selected and how much of the model is visible? |
| Entities | Which domain entities, properties and catalog bindings were compiled? |
| Relationships | Which entities are connected, and does the relationship have an executable binding? |
| Graph | How do entities and concepts connect? Select a node or edge to inspect its details. |
| Diagnostics | Why did acquisition, validation or compilation fail? |
| JSON | What normalized package did Kubling activate for this VDB version? |
Active query surfaces and all compiled sources
The two scope controls show different projections of the same active semantic package:
| View | Contents | Use it for |
|---|---|---|
| Active query surfaces | Definitions mapped to the binding scopes selected by the VDB composition as its intended query interface. | Normal exploration and query generation. |
| All compiled sources | Every definition and binding scope retained in the compiled package, including source-local mappings and their provenance. | Diagnosing composition, projections and model origins. |
A query surface is a selected binding scope, not a data source. For example, a
composition can retain the source-local kube and kube_remote scopes while
publishing a projected fleet scope for normal queries. Kubling keeps all
three in the compiled package, but the active view presents only the entities
and relationships mapped to fleet.
If a composition does not declare query surfaces, the active view falls back to all binding scopes for compatibility.
The example below uses a composed Kubernetes VDB. Scope names and counts vary with the active package.
Query surfaces guide query generation and Studio exploration. They do not grant access, remove catalog objects or instruct Kubling to query every compiled scope. Authentication and VDB policies remain authoritative.

catalogOnly means that the VDB is active without a compiled semantic package.
An invalid state exposes diagnostics rather than presenting a partial graph as
usable. See Semantics for bootstrap, composition and failure
policy.
Semantic relationships and executable bindings v26.5.3+
Open Semantics, select the VDB, choose Graph, and then select Open full graph. Selecting an edge shows whether it only describes the domain or also declares a binding that Kubling can turn into SQL.
A semantic relationship does not have to correspond to a direct relationship between two catalog tables. In this Kubernetes model, a Deployment owns Pods in domain terms, but the catalog-backed ownership path is:
Deployment → ReplicaSet → Pod
Filter the graph to DeploymentOwns and compare the two edges:
Semantic only
DeploymentOwnsPod captures the transitive domain relationship. Studio marks
it Semantic only, identifies the path through DeploymentOwnsReplicaSet
and ReplicaSetOwnsPod, and reports No execution binding. The relationship
is part of the model, but it does not claim that Deployment and Pod can be
joined directly.

Semantic only does not mean that a relationship is invalid or incomplete. It means that the edge has no direct execution binding. Its underlying path can still be modeled as separate relationships with their own execution bindings.
When Copy JOIN SQL is available, Studio copies a bounded JOIN, including a
LIMIT 100, to the clipboard. Paste it into SQL Workspace and adapt its
projection, predicates or limit. Studio never executes copied SQL
automatically.
Generated SQL reflects the currently active semantic package and catalog. Treat it as an editable starting point and review it before execution.
Investigations preview v26.5+
Studio contains an Investigations workspace for the investigation capability,
but it remains disabled. Kubling does not yet expose a read-only runtime-readiness
endpoint that Studio can use to distinguish an available task runtime from a
configured but unreachable one.
The authenticated Task API is the executable interface. It runs synchronously and returns a terminal snapshot. Closing the browser or aborting the HTTP request is not a public task-cancellation operation.
Investigation history in Studio is browser-local presentation state, not a durable task store. The UI can be enabled after the readiness contract is available without changing the public Task API.
Other Studio surfaces
| Surface | What it shows |
|---|---|
| Catalog | VDBs, schemas, tables, columns and provider-reported DDL. |
| Semantics | Compiled entities, relationships, bindings, graph and diagnostics. |
| Investigations | Preview workspace, currently disabled pending a safe runtime-readiness signal. |
| Activity | Live engine, worker-pool, request and session information. |
| Schedules | Configured scheduled JavaScript tasks and their source. |
| Functions | Built-in and module-provided SQL and template functions. |
| Endpoints | Query and action templates plus JavaScript endpoint routes. |
| Modules | Installed JavaScript module-backed data sources and metadata. |
These views describe the selected Kubling instance. They do not replace version-controlled provider configuration, application configuration or VDB descriptors.
Next steps
- Choose a provider for a real source.
- Register a provider in a VDB.
- Compose a semantic model for a federated VDB.
- Configure investigation tasks.
- Review HTTP security before exposing Studio outside a trusted local environment.



