CREATE EXTERNAL TABLE … ENGINE = DATASTREAM

Create a MatrixOne external table that reads rows from a remote DataStream (jstfu) server via the ENGINE = DATASTREAM clause. The table is read-only, requires server, port, and table options, and supports optional recheck and apikey options.

Description

CREATE EXTERNAL TABLE ... ENGINE = DATASTREAM maps a MatrixOne external table to a data source served by a remote DataStream (jstfu) server. MatrixOne streams rows from the server on demand when the table is queried. The table is read-only: SELECT is supported, and writes (INSERT, UPDATE, and DELETE) are rejected.

The statement must provide the server, port, and table options. The optional recheck option controls whether predicates pushed down to the server are re-applied locally, and the optional apikey option presents a shared secret to the server.

Syntax

CREATE EXTERNAL TABLE [IF NOT EXISTS] [db.]table_name (
    column1 type1,
    column2 type2,
    ...
) ENGINE = DATASTREAM [WITH ("option" = 'value' [, "option" = 'value'] ...)];

Arguments

Option	Required	Description
server	Yes	Hostname or IP address of the DataStream server.
port	Yes	Port number of the DataStream server. Must be a valid port number; a non-numeric value is rejected.
table	Yes	Name of the data source to read on the server.
recheck	No	Whether MatrixOne re-applies pushed-down predicates locally. true (default) treats the pushed-down filter as a hint and re-checks rows locally; false trusts the server for the pushed predicates.
apikey	No	Optional shared secret presented to the server. A value of the form env:NAME reads the secret from the process environment variable NAME at scan time so the secret is not stored in catalog metadata, plans, or statement logs.

Usage Notes

• Read-only: external tables backed by DataStream reject INSERT, UPDATE, and DELETE with cannot insert/update/delete from external table.

• Option validation: options are validated when the table is created. Duplicate, unknown, or invalid options are rejected with an invalid input error.

• Secret redaction: SHOW CREATE TABLE round-trips the DDL but never displays the apikey value.

• Filter recheck: a non-pushable predicate always stays local, so it is still applied even when recheck is set to false.

Examples

The following example creates two DataStream external tables, inspects their DDL with SHOW CREATE TABLE, and demonstrates a validation error for a missing required option:

DROP DATABASE IF EXISTS datastream_doc_demo;
CREATE DATABASE datastream_doc_demo;
USE datastream_doc_demo;

CREATE EXTERNAL TABLE ext_file (
    col1 INT,
    col2 DATETIME,
    col3 VARCHAR(50),
    col4 TEXT
) ENGINE = DATASTREAM WITH ('server' = '127.0.0.1', 'port' = '4444', 'table' = 'file_numbers');

SHOW CREATE TABLE ext_file;

CREATE EXTERNAL TABLE ext_keyed (
    col1 INT,
    col2 DATETIME,
    col3 VARCHAR(50),
    col4 TEXT
) ENGINE = DATASTREAM WITH ('server' = '127.0.0.1', 'port' = '4444', 'table' = 'jdbc_numbers', 'recheck' = 'false', 'apikey' = 'top-secret');

SHOW CREATE TABLE ext_keyed;

-- Expected-Success: false
CREATE EXTERNAL TABLE ds_missing_port (a INT) ENGINE = DATASTREAM WITH ('server' = '127.0.0.1');

DROP DATABASE datastream_doc_demo;

See Also

• CREATE EXTERNAL TABLE