Connecter un moteur

Les moteurs de données externes — Spark, Trino, DuckDB, PyIceberg et tout autre client compatible avec le REST Iceberg — se connectent à la façade de catalogue Scrydon à l'adresse :

https://<your-host>/api/table/iceberg

Étape 1 — Émettre un jeton de moteur

Les jetons de moteur sont des identifiants limités à l'organisation qu'un moteur de requête utilise pour s'authentifier auprès du catalogue. Ils portent un indicateur d'écriture facultatif ; les jetons en lecture seule ne peuvent pas effectuer d'opérations POST, PUT, DELETE ou PATCH sur le catalogue. Le rattachement à l'organisation est défini par le serveur à partir de votre session — vous ne pouvez pas émettre de jeton pour une organisation dont vous n'êtes pas membre, et les jetons d'écriture exigent le rôle owner ou admin de l'organisation.

Depuis l'interface (recommandé)

Vous pouvez émettre et gérer des jetons de moteur sans quitter l'application :

• Par table — ouvrez n'importe quelle table Iceberg dans Analytics et accédez à son onglet Query. Activez l'accès en écriture si nécessaire, cliquez sur Generate engine token, et les extraits de connexion situés en dessous sont automatiquement remplis avec votre jeton, l'URI du catalogue, l'espace de noms et le nom de la table.
• À l'échelle de l'organisation — dans l'onglet Query d'une table, cliquez sur Manage and revoke engine tokens (owner/admin de l'organisation) pour créer, lister et révoquer tous les jetons de moteur de l'organisation en un seul endroit. Cette page ne figure pas dans le menu des paramètres de Platform ; elle se trouve à /settings/organization/engine-tokens.

Le jeton n'est affiché qu'une seule fois — copiez-le immédiatement et traitez-le comme un mot de passe : il donne un accès au niveau du catalogue aux tables Iceberg de votre organisation.

Depuis l'API

Un administrateur de l'organisation peut également émettre un jeton directement auprès du point de terminaison des jetons de moteur de la plateforme :

curl -X POST "https://<your-scrydon-host>/api/auth/iceberg/engine-token" \
  -H "Authorization: Bearer <your-platform-session>" \
  -H "content-type: application/json" \
  -d '{"name":"spark-etl","organizationId":"<your-org-id>","canWrite":true}'
# → { "key": "...", "organizationId": "...", "canWrite": true }

Pour restreindre un jeton à un espace de travail, ajoutez "workspaceId" et, éventuellement, "workspaceEnvironmentId". L'espace de travail doit appartenir à l'organisation indiquée dans organizationId et l'environnement à cet espace de travail ; sinon la requête est refusée avec 403, et un identifiant mal formé avec 400. Un jeton ne peut être émis que par ce point de terminaison ou l'interface — les points de terminaison génériques de clés d'API ne peuvent pas définir les champs que porte un jeton de moteur.

Étape 2 — Configurer votre moteur

Tous les moteurs s'authentifient à l'aide du schéma de jeton Bearer (Authorization: Bearer <engine-token>) ou de la propriété de configuration token ci-dessous.

L'URI de catalogue ci-dessous est l'URL de base api-table de votre hôte Scrydon. Dans la plupart des déploiements, il s'agit du même hôte que celui que vous utilisez pour le reste de l'API :

https://<your-host>/api/table/iceberg

Pour le développement local, la valeur par défaut est http://localhost:7500/api/table/iceberg.

from pyiceberg.catalog.rest import RestCatalog

catalog = RestCatalog(
    "scrydon",
    uri="https://<your-host>/api/table/iceberg",
    token="YOUR_ENGINE_TOKEN",
)

# List namespaces
print(catalog.list_namespaces())

# Load a table
tbl = catalog.load_table("my_namespace.my_table")
df = tbl.scan().to_arrow()

-- Install and load the iceberg extension (>=1.0.0 required for REST catalog support)
INSTALL iceberg;
LOAD iceberg;

-- Bearer auth for the Scrydon catalog (OR REPLACE so re-runs don't error)
CREATE OR REPLACE SECRET scrydon_token (TYPE ICEBERG, TOKEN 'YOUR_ENGINE_TOKEN');

-- Attach: the catalog URL is the ENDPOINT option, NOT the ATTACH string.
-- The ATTACH string is the WAREHOUSE — it must be non-empty (your org
-- warehouse, the `prefix` returned by GET /v1/config, i.e. org-<your-org-id>)
-- or DuckDB attaches but lists zero tables.
ATTACH IF NOT EXISTS 'org-<your-org-id>' AS scrydon (
  TYPE ICEBERG,
  SECRET scrydon_token,
  ENDPOINT 'https://<your-host>/api/table/iceberg'
);

-- List tables
SHOW ALL TABLES;

-- Query a table
SELECT * FROM scrydon.my_namespace.my_table LIMIT 10;

-- Time-travel: read a specific snapshot
SELECT * FROM scrydon.my_namespace.my_table AT (VERSION => 1234567890);

connector.name=iceberg
iceberg.catalog.type=rest
iceberg.rest-catalog.uri=https://<your-host>/api/table/iceberg
iceberg.rest-catalog.security=OAUTH2
iceberg.rest-catalog.oauth2.token=YOUR_ENGINE_TOKEN

-- List schemas (namespaces)
SHOW SCHEMAS FROM scrydon;

-- Query a table
SELECT * FROM scrydon.my_namespace.my_table LIMIT 10;

-- Time-travel
SELECT * FROM scrydon.my_namespace.my_table FOR VERSION AS OF 1234567890;

from pyspark.sql import SparkSession

spark = (
    SparkSession.builder
    .appName("scrydon-iceberg")
    .config(
        "spark.sql.extensions",
        "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",
    )
    .config("spark.sql.catalog.scrydon", "org.apache.iceberg.spark.SparkCatalog")
    .config("spark.sql.catalog.scrydon.type", "rest")
    .config(
        "spark.sql.catalog.scrydon.uri",
        "https://<your-host>/api/table/iceberg",
    )
    .config("spark.sql.catalog.scrydon.token", "YOUR_ENGINE_TOKEN")
    # Warehouse hint for /config requests; Scrydon overrides this server-side.
    .config("spark.sql.catalog.scrydon.warehouse", "scrydon")
    .getOrCreate()
)

# List namespaces
spark.sql("SHOW NAMESPACES IN scrydon").show()

# Query a table
spark.sql("SELECT * FROM scrydon.my_namespace.my_table LIMIT 10").show()

# Time-travel
spark.sql(
    "SELECT * FROM scrydon.my_namespace.my_table VERSION AS OF 1234567890"
).show()

org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<version>

-- Step 1: Create a catalog integration pointing at the Scrydon REST facade.
CREATE OR REPLACE CATALOG INTEGRATION scrydon_catalog
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://<your-host>/api/table/iceberg'
    WAREHOUSE   = 'org-<your-org-id>'  -- prefix returned by GET /v1/config
  )
  REST_AUTHENTICATION = (
    TYPE         = BEARER
    BEARER_TOKEN = 'YOUR_READ_ENGINE_TOKEN'
  )
  ENABLED = TRUE;

-- Verify the integration can reach the catalog.
DESCRIBE INTEGRATION scrydon_catalog;

-- Step 2: Create an external volume with direct read access to your
-- org's S3 prefix. The IAM role must have s3:GetObject on the bucket.
CREATE EXTERNAL VOLUME scrydon_vol
  STORAGE_LOCATIONS = ((
    NAME                 = 'scrydon-s3',
    STORAGE_PROVIDER     = 'S3',
    STORAGE_BASE_URL     = 's3://<your-scrydon-bucket>/org-<your-org-id>/',
    STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::<account-id>:role/<role-name>'
  ));

-- Step 3: Register a table backed by the Scrydon catalog.
CREATE ICEBERG TABLE my_table
  CATALOG           = 'scrydon_catalog'
  EXTERNAL_VOLUME   = 'scrydon_vol'
  CATALOG_TABLE_NAME = 'my_table'
  CATALOG_NAMESPACE  = 'my_namespace';

-- Verify: read the first ten rows.
SELECT * FROM my_table LIMIT 10;

org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.7.1

# Configure the Scrydon REST catalog for this Spark session.
spark.conf.set(
    "spark.sql.catalog.scrydon",
    "org.apache.iceberg.spark.SparkCatalog",
)
spark.conf.set("spark.sql.catalog.scrydon.type",  "rest")
spark.conf.set(
    "spark.sql.catalog.scrydon.uri",
    "https://<your-host>/api/table/iceberg",
)
spark.conf.set("spark.sql.catalog.scrydon.token", "YOUR_ENGINE_TOKEN")

# Verify: list available namespaces.
display(spark.sql("SHOW NAMESPACES IN scrydon"))

# Query a table.
display(spark.sql("SELECT * FROM scrydon.my_namespace.my_table LIMIT 10"))

# Time-travel to a specific snapshot.
display(spark.sql(
    "SELECT * FROM scrydon.my_namespace.my_table VERSION AS OF <snapshot_id>"
))

-- Create a foreign catalog backed by the Scrydon REST facade.
-- Requires Unity Catalog and Databricks Premium or Enterprise.
CREATE CATALOG scrydon
USING ICEBERG
OPTIONS (
  'rest.uri' = 'https://<your-host>/api/table/iceberg',
  'token'    = 'YOUR_ENGINE_TOKEN'
);

-- Grant access to workspace members (optional).
GRANT USE CATALOG ON CATALOG scrydon TO `user@example.com`;

-- Query tables.
SELECT * FROM scrydon.my_namespace.my_table LIMIT 10;

-- Time-travel.
SELECT * FROM scrydon.my_namespace.my_table VERSION AS OF <snapshot_id>;

Jusqu'où remonte le voyage dans le temps

Scrydon conserve les snapshots passés d'une table pendant une durée limitée, puis les fait expirer du catalogue. La plupart des tables les conservent 7 jours (votre opérateur peut modifier cette durée). Une table qui valide très souvent — au moins 288 commits au cours de la dernière journée, par exemple un stream qui écrit chaque minute — les conserve 1 jour, afin que les métadonnées de son catalogue restent réduites. Une table qui ralentit revient d'elle-même à la fenêtre plus longue. La lecture d'un snapshot plus ancien que la fenêtre (VERSION AS OF / TIMESTAMP AS OF) échoue, car ce snapshot n'existe plus.

L'expiration d'un snapshot le retire uniquement du catalogue. Scrydon ne supprime pas les fichiers de données de la table.

Ce que renvoie le point de terminaison du catalogue

Sur GET /api/table/iceberg/v1/config, la façade renvoie le préfixe d'entrepôt de votre organisation. C'est ainsi que les clients Iceberg découvrent le bon entrepôt sans que vous ayez à le configurer manuellement. La plupart des clients effectuent cet appel automatiquement.

Accès en écriture

Une écriture par un moteur externe franchit deux contrôles indépendants — les deux doivent l'autoriser :

1. Indicateur d'écriture du jeton de moteur. Le jeton doit être émis avec un accès en écriture (canWrite: true). Les jetons en lecture seule reçoivent 403 Forbidden sur tout POST, PUT, DELETE ou PATCH.
2. Politique d'écriture par table. Chaque table gérée porte une politique d'écriture qui détermine si un moteur externe, quel qu'il soit, peut y effectuer des commits — indépendamment du jeton. Les nouvelles tables sont par défaut en Governed only, ce qui rejette tous les commits externes (même ceux d'un jeton autorisé en écriture) afin que les écritures restent sur le plan de données gouverné.

Modifier la politique d'écriture d'une table

Ouvrez la table dans Analytics → onglet Settings → External write access, puis choisissez une politique d'écriture :

Le moteur StarRocks interne de Scrydon est le seul moteur qui écrit directement des fichiers de données Parquet. Les écritures des moteurs externes (via le catalogue REST) écrivent les métadonnées de table (schémas, snapshots, entrées d'espace de noms) via la façade gouvernée ; les écritures proprement dites du plan de données vont directement vers votre stockage objet à l'aide d'identifiants distribués par Lakekeeper ou signés à distance.

Comment la gouvernance tient en fédération

Un moteur externe se connecte via deux surfaces d'identifiants indépendantes, et Scrydon gouverne chacune d'elles :

1. Métadonnées du catalogue (listes des espaces de noms / tables / schémas / snapshots) — authentifiées par votre jeton de moteur et limitées à l'organisation : un jeton ne voit jamais les tables d'une autre organisation (404 inter-organisations).
2. Octets du plan de données (les fichiers Parquet) — distribués ou signés à distance à chaque requête par la façade, jamais remis en bloc.

Un scan externe brut lit les fichiers Parquet tels qu'ils sont stockés, si bien que les masques par colonne — que Scrydon applique comme une transformation au moment de la lecture — ne sont pas intégrés à ces octets. La gouvernance s'exerce donc différemment sur chaque surface.

Lectures — accès brut soumis à l'habilitation (pas de masques par colonne)

Avant de distribuer des identifiants de plan de données pour une table, la porte de distribution pour scan brut de la façade résout l'habilitation effective de l'utilisateur du jeton de moteur. Si la classification d'une colonne dépasse cette habilitation, la distribution pour scan brut est refusée — un utilisateur qui ne pourrait voir une colonne que masquée dans le chemin gouverné ne peut pas obtenir d'identifiants bruts pour la lire en clair. Il s'agit d'un contrôle d'accès obligatoire qui prime sur le partage discrétionnaire : il refuse même les administrateurs de l'organisation qui n'ont pas l'habilitation requise.

• Besoin d'un masquage par colonne appliqué aux données elles-mêmes ? Lisez via le plan de données gouverné — le SDK de notebook scrydon, l'interface Analytics ou POST /data/v1/tables/:ref/query — qui exécute le noyau de sélection masquée et renvoie des cellules masquées ainsi qu'une liste maskedColumns.
• Les moteurs à accès S3 direct (volume externe Snowflake, STS Databricks) lisent les octets avec leurs propres identifiants cloud, en dehors du signataire de Scrydon. Scrydon ne peut ni masquer ces lectures ni les soumettre au contrôle d'habilitation — appliquez les politiques de lignes/colonnes propres au moteur, et n'accordez à ces intégrations des jetons que pour les tables dont vous acceptez le partage intégral au regard de leur sensibilité.

Écritures — la politique d'écriture par table

Chaque table gérée porte une politique d'écriture (voir Accès en écriture ci-dessus) : governed_only (par défaut) rejette tous les commits externes au niveau de la façade ; open_append / open_full les acceptent et la plateforme réconcilie le nouveau snapshot a posteriori (événement d'audit, rafraîchissement du nombre de lignes, réapplication de la gouvernance). Un jeton de moteur autorisé en écriture reçoit tout de même un 403 sur une table governed_only.

Les métadonnées de gouvernance accompagnent la table

Scrydon inscrit la gouvernance sur la table Iceberg elle-même sous forme de propriétés — scrydon.classification, scrydon.write-policy, scrydon.identity-columns, scrydon.column-sensitivity — de sorte que tout outil compatible avec le catalogue qui inspecte la table voit sa classification des données et ses colonnes d'identité sans appeler d'API Scrydon.

Matrice de compatibilité

Les moteurs vérifiés par la CI sont testés contre la façade REST de Scrydon à chaque pull request qui touche la surface Iceberg (workflow test-iceberg-compat.yml). Les moteurs vérifiés par la communauté ont été validés manuellement mais ne font pas encore partie de la matrice automatisée.

Les opérations de catalogue (liste des espaces de noms / tables / schémas / snapshots) constituent le contrat systématiquement vérifié pour les moteurs testés en CI. Les lectures du plan de données dépendent de votre backend de stockage (voir la note 1 ci-dessous).

Écrire depuis un moteur de streaming

Pour injecter des données en flux ou par lots dans une table gérée depuis Spark Structured Streaming, Flink ou le connecteur Iceberg sink de Kafka Connect, consultez Écriture externe. Les commits passent par cette même façade de catalogue sous une politique d'écriture open_append, et Scrydon les réconcilie sous gouvernance a posteriori.

Feuille de route

Deux capacités sont conçues et subordonnées à la prise en charge par les moteurs en amont — elles ne sont pas encore disponibles :

• Lectures interactives à la vitesse d'Arrow (Arrow Flight SQL). Un point de terminaison StarRocks Arrow Flight SQL servi par un intermédiaire, protégé par une authentification par jeton avec des descripteurs de requêtes masquées, afin que les lectures interactives atteignent de bout en bout le débit Arrow natif du moteur sans exposer de SQL gouverné brut ni d'identifiants StarRocks. Subordonné au provisionnement du point de terminaison Flight SQL dans le déploiement.
• Iceberg format v3. Vecteurs de suppression (merge-on-read plus rapide) et lignage des lignes (provenance d'audit des commits renforcée). Subordonné à la matrice de compatibilité — StarRocks et PyIceberg doivent tous deux lire et écrire le format v3 avant que Scrydon n'écrive une table v3.

Renouveler ou révoquer un jeton de moteur

Les jetons peuvent être révoqués à tout moment depuis la page des jetons de moteur de l'organisation — ouvrez-la avec Manage and revoke engine tokens dans l'onglet Query de n'importe quelle table (owner/admin de l'organisation). La révocation prend effet immédiatement ; les connexions existantes qui utilisent le jeton recevront 401 Unauthorized à la requête suivante.