Register, review, and query Parquet

An administrator sets this environment variable before starting the server:

Restart through the normal service procedure so the process receives the setting. Registration requires schema-management permission. Use a small Parquet file readable on the server for the first connection.

Save the following JSON as connect-source.json. Replace YOUR_DATABASE_ID, YOUR_TENANT, YOUR_ACTOR, and the file URI. The database in the body must match the database selected by x-shrikedb-database; request credentials still determine authorization.

Send it with the variables established in the MCP setup:

Add the credential header for an authenticated server. Inspect the JSON-RPC error field before reading result. Save the returned source ID, dataset ID, manifest hash, and freshness hash. A registration receipt records the source definition; it does not activate a graph mapping.

To call lakehouse_list_connections or lakehouse_connection_status, send database_id, tenant, and actor; no source URI or credential is needed for these read actions. The connections array lists each visible source’s ID, dataset ID, format, file count, byte count, and recorded freshness hash. It contains no credential or source URI. Some receipt fields are populated only for registration or refresh actions.

lakehouse_profile_connection accepts database_id, tenant, and actor. For local Parquet sources, the response lists columns and types, total row count, and key and relationship candidates. The profiler samples up to eight files across a partitioned source, with a combined limit of 2,048 rows. A schema mismatch among sampled files suppresses key suggestions and appears in status. Candidate keys are non-null and unique in the sample; relationship candidates have matching sampled values. Review these suggestions against the complete source and business meaning before preparing a mapping. The profile does not publish a mapping.

A draft identifies:

Use the lakehouse_validate_mapping_draft schema from tools/list for the complete request structure. Keep draft and source identifiers consistent. Check null keys, duplicate keys, relationship direction, and representative expected rows against the source file. Submit the draft to lakehouse_update_mapping_draft to store it in the database catalog. lakehouse_list_mapping_drafts returns the database’s saved drafts after reconnecting or restarting. To retrieve one, call lakehouse_get_mapping_draft with database_id, tenant, actor, and draft_id. Draft updates require a registered source and dataset in the selected database.

Submit the draft to lakehouse_validate_mapping_draft and inspect validation.valid and validation.errors. The validator checks scope, fields, confidence range, and lineage-hash syntax; it does not verify the complete source’s key uniqueness or foreign-key meaning. The key-containment, null-key, and sample-oracle pass fields remain false until those checks are implemented. Fix reported problems and review the actual field mapping and representative source rows before proceeding.

Use lakehouse_save_mapping to save the reviewed draft, then lakehouse_publish_mapping to activate it. Both take the draft in their argument object. Save the proposal and published mapping IDs returned by these calls. When using expected_catalog_hash, obtain a current catalog hash through your catalog-management client; a stale value is rejected so an earlier review cannot overwrite newer catalog state.

Call lakehouse_list_mapping_proposals to inspect the database’s saved proposal IDs, dataset IDs, hashes, and review states. This is useful after a restart or when several people are preparing mappings.

Publishing activates a view over the source; source Parquet files remain unchanged.

lakehouse_query_execute takes database, tenant, actor, mode, and mode-specific query inputs. Inspect its current schema with tools/list. Supported semantic requests use a published mapping. Read-only Cypher and SPARQL requests can name a published mapping explicitly; the same source-bound forms also work through the regular language query endpoints when lakehouse is enabled. Use the mapping ID returned by lakehouse_publish_mapping.

A Cypher source query projects reviewed Parquet columns with CALL lakehouse.scan, YIELD, RETURN, and a required LIMIT:

A SPARQL source query uses a local SERVICE IRI. The column IRIs refer to mapped Parquet columns; they do not make a network request:

Send either query to POST /api/v1/query/direct with your API key in x-shrikedb-api-key, mode set to cypher or sparql, and the selected database in x-shrikedb-database when it is not the default. For example:

The source forms execute a bounded projection from one local Parquet source. LIMIT must be between 1 and 1,000, and an RPC limit can lower it. The projected columns must be covered by the reviewed mapping and stored as required, non-repeated Boolean, UTF-8, 32/64-bit integer, or 32/64-bit floating-point columns in every registered file. Joins, aggregation, filtering, DISTINCT, ORDER BY, OFFSET, and graph snapshot versions are not part of these source forms; use stored graph queries or a supported semantic source request for those operations. The current source result binds column values as strings. Ordinary Cypher and SPARQL queries continue to use stored graph/RDF data.

Before treating rows as source data, inspect the response:

Compare a small result with known rows from the original file, and inspect the source-read diagnostics.

For a single mapped concept, semantic requests can count rows, group count and sum by a mapped column, and filter with equality or numeric and string ranges. A row count without filters uses Parquet metadata. Grouped requests scan the required columns across the complete source before applying the result limit. A projection request filters rows before limiting results. Multi-concept joins require the graph query path.

A registered local Parquet source has a fixed file list and recorded file metadata. If a registered file disappears or its size or modification time changes, queries return an error instead of a partial result. Keep files immutable while a mapping is active. To use a changed source today, create a new database connection and reviewed mapping, then switch clients to that database. lakehouse_refresh_connection_manifest replays an unchanged registration; it rejects a changed source definition. Retain the older files when you need to reproduce earlier answers, because a catalog backup does not copy external data.