> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nx1cloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Match model to catalog

> Match a model definition against catalog metadata using AI. The AI scans
the domain's datasets to find the best matching source tables and columns.

You can use this during manual model creation to auto-fill source tables,
columns, and SQL from the catalog.

**Required roles**: `nx1_semantic_modeller` or `nx1_semantic_admin`



## OpenAPI

````yaml post /api/semantic-models/match
openapi: 3.1.0
info:
  title: Nx1 AI API
  description: |

    AI API for Nx1 Data Platform Management and Automated Data Tasks.

    Authentication is required via PSK in Authorization header.

    Default PSK is | [ask a friend] |
  version: 0.10.2
servers: []
security: []
paths:
  /api/semantic-models/match:
    post:
      tags:
        - Semantic models
      summary: Match model to catalog
      description: >-
        Match a model definition against catalog metadata using AI. The AI scans

        the domain's datasets to find the best matching source tables and
        columns.


        You can use this during manual model creation to auto-fill source
        tables,

        columns, and SQL from the catalog.


        **Required roles**: `nx1_semantic_modeller` or `nx1_semantic_admin`
      operationId: match_model_to_catalog_api_semantic_models_match_post
      parameters:
        - name: x-correlation-id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Correlation-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MatchModelRequest'
      responses:
        '200':
          description: Matched model with source tables and columns
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchModelResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2AuthorizationCodeBearer: []
        - APIKeyHeader: []
components:
  schemas:
    MatchModelRequest:
      properties:
        model_name:
          type: string
          title: Model Name
          description: Name of the model being defined.
        model_description:
          type: string
          title: Model Description
          description: What the model should represent.
          default: ''
        desired_columns:
          items:
            $ref: '#/components/schemas/MatchModelColumn'
          type: array
          title: Desired Columns
          description: Desired columns/metrics the model should expose.
          default: []
        domain_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain Name
          description: Domain name. Either domain_name or domain_urn required.
        domain_urn:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain Urn
          description: Domain URN. Either domain_name or domain_urn required.
        include_tables:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Include Tables
          description: Only consider these tables.
        exclude_tables:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Tables
          description: Exclude these tables from consideration.
        target_catalog:
          type: string
          title: Target Catalog
          description: Target Trino catalog.
          default: iceberg
        target_schema:
          anyOf:
            - type: string
            - type: 'null'
          title: Target Schema
          description: Target Trino schema.
      type: object
      required:
        - model_name
      title: MatchModelRequest
      description: Request to match a model definition against catalog metadata.
    MatchModelResponse:
      properties:
        model_name:
          type: string
          title: Model Name
        model_description:
          type: string
          title: Model Description
        source_tables:
          items:
            $ref: '#/components/schemas/MatchedSourceTable'
          type: array
          title: Source Tables
          default: []
        columns:
          items:
            $ref: '#/components/schemas/MatchedColumn'
          type: array
          title: Columns
          default: []
        generated_sql:
          type: string
          title: Generated Sql
          description: AI-generated SQL for the view.
          default: ''
        overall_confidence:
          type: number
          title: Overall Confidence
          description: Overall match confidence between 0-1.
          default: 0
        ai_reasoning:
          type: string
          title: Ai Reasoning
          description: AI explanation of the matching strategy.
          default: ''
        warnings:
          items:
            type: string
          type: array
          title: Warnings
          description: Any warnings about the match.
          default: []
      type: object
      required:
        - model_name
        - model_description
      title: MatchModelResponse
      description: Response from catalog matching.
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
          description: A brief description of the error that occurred.
        code:
          type: integer
          title: Code
          description: The HTTP status code associated with the error.
          default: 500
      type: object
      required:
        - error
      title: ErrorResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MatchModelColumn:
      properties:
        name:
          type: string
          title: Name
          description: Desired column/metric name.
        description:
          type: string
          title: Description
          description: What this column should represent.
          default: ''
        role:
          anyOf:
            - type: string
            - type: 'null'
          title: Role
          description: Dimension, measure, or key.
      type: object
      required:
        - name
      title: MatchModelColumn
      description: A desired column in the model to match against catalog.
    MatchedSourceTable:
      properties:
        qualified_name:
          type: string
          title: Qualified Name
          description: Fully qualified table name.
        relevance_score:
          type: number
          title: Relevance Score
          description: How relevant this table is. Relevance score is between 0-1.
          default: 0
        reasoning:
          type: string
          title: Reasoning
          description: Why this table is relevant.
          default: ''
        columns_used:
          type: integer
          title: Columns Used
          description: Number of columns used from this table.
          default: 0
      type: object
      required:
        - qualified_name
      title: MatchedSourceTable
      description: A source table that was matched from the catalog.
    MatchedColumn:
      properties:
        column_name:
          type: string
          title: Column Name
          description: Technical column name for the view.
        business_name:
          type: string
          title: Business Name
          description: Business-friendly display name.
        description:
          type: string
          title: Description
          description: Column description.
          default: ''
        source_table:
          type: string
          title: Source Table
          description: Source table qualified name.
        source_column:
          type: string
          title: Source Column
          description: Source column name.
        data_type:
          type: string
          title: Data Type
          description: Trino data type.
        is_key:
          type: boolean
          title: Is Key
          default: false
        is_dimension:
          type: boolean
          title: Is Dimension
          default: false
        is_measure:
          type: boolean
          title: Is Measure
          default: false
        is_nullable:
          type: boolean
          title: Is Nullable
          default: true
        transformation_sql:
          anyOf:
            - type: string
            - type: 'null'
          title: Transformation Sql
          description: SQL transformation if needed.
        confidence:
          type: number
          title: Confidence
          description: Confidence score between 0-1 for this match.
          default: 0
        match_reasoning:
          type: string
          title: Match Reasoning
          description: Why the AI matched the column.
          default: ''
      type: object
      required:
        - column_name
        - business_name
        - source_table
        - source_column
        - data_type
      title: MatchedColumn
      description: A matched column from the catalog.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    OAuth2AuthorizationCodeBearer:
      type: oauth2
      flows:
        authorizationCode:
          scopes: {}
          authorizationUrl: >-
            https://sso-rapid.rapid.nx1cloud.com/realms/rapid/protocol/openid-connect/auth
          tokenUrl: >-
            https://sso-rapid.rapid.nx1cloud.com/realms/rapid/protocol/openid-connect/token
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization-PSK

````