Statements

Catalog, namespace, table, view, materialization, inspection and session statements.

Catalog and namespace

Statement	Purpose
`ATTACH CATALOG registered_name AS alias`	Attach a workspace-registered catalog to this session.
`DETACH alias`	Remove a session attachment. The registration remains.
`USE [catalog.]schema`	Set the current namespace for unqualified names.
`CREATE SCHEMA [IF NOT EXISTS] name`	Create a schema in a writable managed catalog.
`DROP SCHEMA [IF EXISTS] name [RESTRICT	CASCADE]`

Register catalogs and bind Secrets in the Vegalake workspace. SQL attachment selects an approved catalog; it cannot introduce arbitrary storage credentials.

Secrets

CREATE [OR REPLACE] PERSISTENT SECRET secret_name (
  TYPE secret_type,
  PROVIDER CONFIG,
  property value,
  ...
);

SHOW SECRETS;
DROP PERSISTENT SECRET [IF EXISTS] secret_name;

Supported types are S3, GCS, AZURE, POSTGRESQL, ICEBERG_OAUTH2, HTTP_BEARER and HTTP_BASIC. Required properties depend on the type. Secret creation requires TLS, SECRET_ADMIN, the simple-query protocol and no active transaction. Prepared creation is deliberately unavailable because parameters would retain credentials in prepared-statement state.

CREATE OR REPLACE rotates a secret by adding a new active version. SHOW SECRETS returns redacted metadata only. DROP revokes the logical secret without making old encrypted values readable. See Lakehouse federation: create a secret directly for complete S3, GCS, Azure, PostgreSQL and Iceberg examples.

Tables

CREATE TABLE [IF NOT EXISTS] [catalog.]schema.table_name (
  column_name data_type [NOT NULL] [DEFAULT expression],
  ...
);

CREATE TABLE new_table AS SELECT ...;
DROP TABLE [IF EXISTS] table_name [RESTRICT | CASCADE];

ALTER TABLE supports the managed catalog's schema evolution rules. External open-table formats can reject a change that their current writer contract cannot publish safely.

Data modification

INSERT INTO target [(column, ...)]
SELECT ...;

UPDATE target
SET amount = amount * 1.05
WHERE region = 'me';

DELETE FROM target
WHERE loaded_at < current_date - INTERVAL '90 days';

MERGE INTO target t
USING changes s
ON t.id = s.id
WHEN MATCHED THEN UPDATE SET value = s.value
WHEN NOT MATCHED THEN INSERT (id, value) VALUES (s.id, s.value);

Write availability depends on the catalog and table format. The public PostgreSQL transaction surface is currently read-only; managed writes run through the VegaDB write service and statements the service admits. Do not assume a PostgreSQL driver's transaction mode implies PostgreSQL storage semantics.

Views

CREATE [OR REPLACE] VIEW reporting.active_customers AS
SELECT * FROM customers WHERE status = 'active';

DROP VIEW reporting.active_customers;

For physically stored results use CREATE MATERIALIZED VIEW; for continuous incremental maintenance use the preview CREATE STREAMING MATERIALIZED VIEW. The complete lifecycle is in Materialized views.

Import and export

VegaDB table registration and VegaFlow are the normal cloud ingestion paths. User SQL does not accept object-store secrets or local machine paths. Where a managed catalog enables COPY, the location must resolve through an authorized external table or managed stage.

Inspection

Statement	Output
`EXPLAIN query`	Distributed physical plan and fragment boundaries.
`EXPLAIN ANALYZE query`	Plan plus observed execution metrics.
`DESCRIBE table`	Bound columns and data types.
`SHOW TABLES`	Visible tables in the current namespace.
`SHOW SCHEMAS`	Visible schemas.
`SHOW STREAMING MATERIALIZED VIEWS`	Planned streaming-view state surface.
`SUMMARIZE table_or_query`	Column summary using distributed mergeable states.

Prepared statements

Most applications should use their driver’s prepared-statement API. SQL-level PREPARE/EXECUTE support can vary by endpoint; the PostgreSQL extended protocol is the stable client contract.

Transactions

BEGIN READ ONLY;
SELECT ...;
COMMIT;

The PostgreSQL endpoint supports read-only READ COMMITTED transaction blocks and failed-transaction recovery. Writes, savepoints, repeatable read, serializable, deferrable and two-phase commit are not currently supported through that endpoint.

On this page