Semantic Layer Foundation

The Semantic Layer is the foundation that enables intelligent data discovery and schema management across the entire MCP server. It automatically bridges AI models and the XAPClosed GigaSpaces eXtreme Application Platform. Provides a powerful solution for data processing, launching, and running digital services data model by providing rich metadata, relationship information, and smart caching mechanisms. Its includes, type descriptions, field description, relationship definitions and description of user defined tools and their parameters.

The metadata information is kept on dedicated space with mode META that will be automatically deployed when the first MCP server is created.

Core Semantic Tools

  • space_list_types — Discover all data types registered in a space

  • space_describe_type — Get complete schema with properties, indexes, and relations

  • meta_get_space — Retrieve cached space metadata and type summaries

  • meta_get_types — Get all type metadata with their FQNs and aliases

  • meta_get_user_details — Access human-readable field aliases and format hints

  • meta_list_spaces — List all spaces with metadata from the meta-space cache

Key Features

Schema Introspection

Automatically discover exact property names, Java types, indexes, and ID/routingClosed The mechanism that is in charge of routing the objects into and out of the corresponding partitions. The routing is based on a designated attribute inside the objects that are written to the Space, called the Routing Index. properties. Never guess column names — the semantic layer provides the ground truth.

Example output from space_describe_type:

 {
  "typeName": "com.example.Order",
  "properties": [
    { "name": "id", "javaType": "long", "index": "BASIC" },
    { "name": "customerId", "javaType": "String" },
    { "name": "totalAmount", "javaType": "double" },
    { "name": "status", "javaType": "String" }
  ],
  "idProperty": "id",
  "routingProperty": "customerId"
}

Relationship Mapping

Understand foreign-key relationships between types (one-to-many, many-to-one, many-to-many). Relationships are cached with their FQN, join columns, and directionality.

Example:

Order → Customer (via customerId = id)Order → Product (via productId = id)

Metadata Caching

A dedicated "meta-space" maintains fast, indexed access to schema metadata without hitting live space descriptors. This enables rapid schema discovery and eliminates repeated network calls. (Tiered storageClosed Automatically assigns data to different categories of storage types based on considerations of cost, performance, availability, and recovery. space to keep metadata persistence)

Human-Readable Aliases

Maps technical field names to user-friendly aliases, providing format hints (e.g., date formats, enum values) to guide AI in generating correct data types and values.

Example:

createdDate (technical name) → Created (alias) with format yyyy-MM-dd HH:mm:ss
tier (technical name) → Customer Tier (alias) with format GOLD|SILVER|BRONZE

FQN Resolution

AI is instructed to use fully-qualified type names (FQN) as returned by the semantic layer. Never use human aliases or shortened names as typeName parameters — they will cause failures.

Correct: com.gigaspaces.examples.model.Order

Incorrect: Order or OrderData

Semantic Workflow for MCP tools

When performing any data operation, follow this workflow:

  1. Discover SpaceClosed Where GigaSpaces data is stored. It is the logical cache that holds data objects in memory and might also hold them in layered in tiering. Data is hosted from multiple SoRs, consolidated as a unified data model. → Call meta_get_space(spaceName) to get cached metadata and type list

  2. Inspect Schema → Call space_describe_type(spaceName, typeName) to get exact field names and types

  3. Resolve Aliases → If user provided human aliases, call meta_get_user_details(uuid) to resolve them to original field names

  4. Construct Operation → Use the exact FQN and field names from the semantic layer

User Input: "Write an order for customer John"
↓
meta_get_space("orders") → [Order, Customer, Product, ...]
↓
space_describe_type("orders", "com.example.Order") → fields: [id, customerId, productId, totalAmount, status, ...]
↓
meta_get_user_details(customerUuid) → customerId is field "customerId", not "customer_id"
↓
space_write("orders", "com.example.Order", {"id": 123, "customerId": "john", ...})

Why It Matters

The semantic layer ensures that AI-generated queries and data operations are always semantically correct, even with:

  • Complex schema with many types

  • Numerous relationships and JOINs

  • User-provided aliases and human-readable names

  • Multiple Java types and format conventions

Prevents Common Mistakes:

  • ❌ Using human aliases instead of FQN in tool parameters

  • ❌ Guessing at column names that don't match the actual schema

  • ❌ Missing relationships that would require JOINs

  • ❌ Using incorrect Java types when writing data

  • ❌ Not understanding field formats (dates, enums, etc.)

Access Tier Summary

Tier

Description

Examples
Tier 0: Read-Only Unrestricted read access, no confirmation needed space_query, space_sql, space_count, space_aggregate

Tier 1: Write

Data modification operations

space_write, space_change, space_take, space_write_batch

Tier 2: Compute

Distributed task and remote service execution

space_execute_registered_task, space_execute_distributed_task

Tier 3: Admin

Cluster and infrastructure management

cluster_get_topology, space_create, puClosed This is the unit of packaging and deployment in the GigaSpaces Data Grid, and is essentially the main GigaSpaces service. The Processing Unit (PU) itself is typically deployed onto the Service Grid. When a Processing Unit is deployed, a Processing Unit instance is the actual runtime entity._deploy, manager_restart