@microsoft/rayfin-connector-eventhouse
Marker, runtime, config, saved-query input, raw response, and normalization APIs for Fabric Eventhouse (KQL database) connectors — formerly @microsoft/rayfin-connector-kusto.
@microsoft/rayfin-connector-eventhouse provides the eventhouse connector marker, its
configuration types, its runtime, and result normalization. Register the runtime with
connectorsService from @microsoft/rayfin-connectors. See
Eventhouse (KQL databases) for guide-level usage and for
migrating from 1.36.
Rayfin 2.0 renames @microsoft/rayfin-connector-kusto to this package. New Eventhouse
authoring is held in 2.0.0: the package serves projects that already declare an eventhouse
connector.
Installation
npm install @microsoft/rayfin-connector-eventhouse@2.0.0 @microsoft/rayfin-connectors@2.0.0Install both at the exact version of the project's @microsoft/rayfin-cli, and uninstall
@microsoft/rayfin-connector-kusto.
Renamed exports
@microsoft/rayfin-connector-kusto (1.36) | @microsoft/rayfin-connector-eventhouse (2.0) |
|---|---|
Kusto | Eventhouse |
kusto() | eventhouse() |
KustoConnectorConfig | EventhouseConnectorConfig |
KustoOperation, KustoOperationCatalog | EventhouseOperation, EventhouseOperationCatalog |
KustoQueryResponse, KustoCommandResponse | EventhouseQueryResponse, EventhouseCommandResponse |
KustoV1Table, KustoV1Column | EventhouseV1Table, EventhouseV1Column |
KustoTable, KustoColumn | EventhouseTable, EventhouseColumn |
KustoQueryResult, KustoQueryError, KustoCorrelation | EventhouseQueryResult, EventhouseQueryError, EventhouseCorrelation |
| — | EventhouseClientConfig, EventhouseParameterValue |
ExecuteQueryInput, ExecuteCommandInput, and toQueryResult keep their names; the inputs
change shape, as shown below.
Marker and operation catalog
Eventhouse<TOps> is the connector marker. It defaults to both operations, executeQuery
and executeCommand.
import type { OperationDef } from '@microsoft/rayfin-connectors';
import type {
Eventhouse,
EventhouseClientConfig,
EventhouseCommandResponse,
EventhouseQueryResponse,
ExecuteCommandInput,
ExecuteQueryInput,
} from '@microsoft/rayfin-connector-eventhouse';
type EventhouseOperation = 'executeQuery' | 'executeCommand';
interface EventhouseOperationCatalog {
executeQuery: OperationDef<ExecuteQueryInput, EventhouseQueryResponse>;
executeCommand: OperationDef<ExecuteCommandInput, EventhouseCommandResponse>;
}
type AppConnectorsSchema = {
telemetry: Eventhouse<'executeQuery' | 'executeCommand'>;
};The marker accepts EventhouseClientConfig, so connectorsService rejects a config for
another connector type under that name. The operation outputs are the raw native Kusto v1
{ Tables } document. Normalize them with toQueryResult.
Inputs
Both operations name a query saved in the connector's additionalPayload in rayfin.yml and
pass its parameter values. Neither accepts query text, the cluster, or the database.
type EventhouseParameterValue =
| string
| number
| boolean
| (string | number | boolean | null)[];
interface ExecuteQueryInput {
queryId: string;
parameters?: Record<string, EventhouseParameterValue>;
clientRequestId?: string;
}
interface ExecuteCommandInput {
queryId: string;
parameters?: Record<string, EventhouseParameterValue>;
clientRequestId?: string;
}executeCommand runs a saved management command against the cluster's /v1/rest/mgmt
endpoint instead of /v1/rest/query. clientRequestId is forwarded as the
x-ms-client-request-id header and never appears in the response body. See
Pass user input as parameters for
how to send each parameter type.
Config types
interface EventhouseClientConfig extends ConnectorConfig {
connector: 'eventhouse';
}
interface EventhouseConnectorConfig extends EventhouseClientConfig {
queryServiceUri: string;
databaseName: string;
}EventhouseClientConfig is what registering the connector requires. EventhouseConnectorConfig
is the shape of connectorConfig in rayfin/connectors/<name>/schema.ts; its
queryServiceUri and databaseName are informational and never sent with a request. The
connector function reads the cluster, the database, and the saved queries from
additionalPayload. Both types are exported from this package, not from
@microsoft/rayfin-connectors.
Runtime
function eventhouse(): ConnectorRuntime;eventhouse() registers invoke middleware for executeQuery and executeCommand. It adds
a clientRequestId in the KPC.rayfin_eventhouse_v1;<uuid> format when the caller omits
one and Web Crypto is available, and otherwise forwards the input unchanged. It never adds the
cluster or database.
The 1.36 kusto() runtime merged queryServiceUri and databaseName from the generated
config into each request. eventhouse() does not.
Raw response and normalization
interface EventhouseQueryResponse {
Tables?: EventhouseV1Table[];
}
type EventhouseCommandResponse = EventhouseQueryResponse;
interface EventhouseV1Table {
TableName?: string;
Columns?: EventhouseV1Column[];
Rows?: unknown[];
}
interface EventhouseV1Column {
ColumnName?: string;
ColumnType?: string;
DataType?: string;
}
function toQueryResult(
response: EventhouseQueryResponse,
correlation?: EventhouseCorrelation,
): EventhouseQueryResult;toQueryResult transforms the native Kusto v1 response into a discriminated result that
preserves every returned table:
type EventhouseQueryResult =
| {
status: 'success';
tables: EventhouseTable[];
clientRequestId: string;
activityId?: string;
}
| {
status: 'error';
error: EventhouseQueryError;
clientRequestId: string;
activityId?: string;
};
interface EventhouseTable {
name: string;
columns: EventhouseColumn[];
rows: unknown[][];
}
interface EventhouseColumn {
name: string;
type: string;
}
interface EventhouseCorrelation {
clientRequestId?: string;
activityId?: string;
}
interface EventhouseQueryError {
message: string;
code?: string;
}clientRequestId and activityId are out-of-band correlation values. Pass what you know to
toQueryResult; they are not read from the native response body, and both default to empty.
A call the connector function refuses does not resolve to a result: it throws a
NetworkError from @microsoft/rayfin-client whose serverErrorCode is one of the
Eventhouse error codes.
@microsoft/rayfin-connector-fabric-iq-mcp
Marker, runtime, conversation wrapper, tool calls, task progress, errors, and protocol helpers for the Fabric IQ MCP connector (fabriciqmcp).
@microsoft/rayfin-app-state-fabric
SDK reference for Fabric-hosted deep-link state: createFabricAppStateClient, state limits, capabilities, listeners, and errors.