ColumnSource (General SQL Parser Java Library Core 4.1.0.5 API)

Object
- gudusoft.gsqlparser.resolver2.model.ColumnSource

```
public class ColumnSource
extends Object
```
Represents the source of a column reference. Tracks where a column comes from, including intermediate transformations through subqueries and CTEs. Design principles: 1. Immutable - once created, cannot be modified 2. Recursive - can trace back through subquery/CTE layers 3. Confidence-scored - supports evidence-based inference

Constructor Summary

Constructors
Constructor and Description
`ColumnSource(INamespace sourceNamespace, String exposedName, TParseTreeNode definitionNode)` Constructor for definite matches (confidence = 1.0)
`ColumnSource(INamespace sourceNamespace, String exposedName, TParseTreeNode definitionNode, double confidence, String evidence)`
`ColumnSource(INamespace sourceNamespace, String exposedName, TParseTreeNode definitionNode, double confidence, String evidence, TTable overrideTable)`
`ColumnSource(INamespace sourceNamespace, String exposedName, TParseTreeNode definitionNode, double confidence, String evidence, TTable overrideTable, List<TTable> candidateTables)`
`ColumnSource(INamespace sourceNamespace, String exposedName, TParseTreeNode definitionNode, double confidence, String evidence, TTable overrideTable, List<TTable> candidateTables, ResolutionEvidence evidenceDetail)` Full constructor with all fields including ResolutionEvidence.
`ColumnSource(INamespace sourceNamespace, String exposedName, TParseTreeNode definitionNode, double confidence, String evidence, TTable overrideTable, List<TTable> candidateTables, ResolutionEvidence evidenceDetail, FieldPath fieldPath)` Full constructor with all fields including ResolutionEvidence and FieldPath.
`ColumnSource(INamespace sourceNamespace, String exposedName, TParseTreeNode definitionNode, ResolutionEvidence evidenceDetail)` Constructor with ResolutionEvidence (preferred for new code).
`ColumnSource(INamespace sourceNamespace, String exposedName, TParseTreeNode definitionNode, ResolutionEvidence evidenceDetail, TTable overrideTable)` Constructor with ResolutionEvidence and override table.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`List<TTable>`	`getAllFinalTables()` Get all physical tables that this column might originate from.
`Map<TTable,Integer>`	`getCandidateTableDdlStatus()` Get DDL verification status for all candidate tables.
`List<TTable>`	`getCandidateTables()` Get the candidate tables for ambiguous columns.
`double`	`getConfidence()`
`static int`	`getDdlVerificationStatus(TTable table, String columnName)` Check DDL verification status for a candidate table.
`SourceLocation`	`getDefinitionLocation()`
`TParseTreeNode`	`getDefinitionNode()`
`String`	`getEvidence()`
`ResolutionEvidence`	`getEvidenceDetail()` Get the structured evidence detail for this resolution.
`EvidenceType`	`getEvidenceType()` Get the evidence type from the structured evidence detail.
`String`	`getExposedName()`
`FieldPath`	`getFieldPath()` Get the field path for deep/record field access.
`String`	`getFinalColumnName()` Get the original column name in the physical table when this column is an alias.
`TTable`	`getFinalTable()` Get the final physical table this column originates from after tracing through all subqueries and CTEs.
`TTable`	`getOverrideTable()` Get the override table, if set.
`INamespace`	`getSourceNamespace()`
`boolean`	`hasDefiniteEvidence()` Check if this resolution has definite evidence (not inferred).
`boolean`	`hasFieldPath()` Check if this column source has a field path (deep/record field access).
`static boolean`	`hasTableDdl(TTable table)` Check if a table has DDL metadata available (from CREATE TABLE in same script).
`boolean`	`isAmbiguous()` Check if this column has multiple candidate tables (is ambiguous).
`boolean`	`isCalculatedColumn()` Check if this column source represents a calculated expression.
`boolean`	`isColumnAlias()` Check if this column source represents a column alias (renamed column).
`static boolean`	`isColumnInTableDdl(TTable table, String columnName)` Check if a column exists in a table's DDL definition.
`boolean`	`isCTEExplicitColumn()` Check if this column is a CTE explicit column with a different name than the underlying column.
`boolean`	`isDefinite()` Checks if this is a definite resolution (confidence = 1.0)
`boolean`	`isInferred()` Checks if this is an inferred resolution (confidence < 1.0)
`boolean`	`isStructFieldAccess()` Check if this is a struct field access (has evidence "struct_field_access").
`String`	`toString()`
`ColumnSource`	`withCandidateTables(List<TTable> candidates)` Creates a copy with candidate tables.
`ColumnSource`	`withConfidence(double newConfidence, String newEvidence)` Deprecated. Use `withEvidence(ResolutionEvidence)` instead
`ColumnSource`	`withEvidence(ResolutionEvidence newEvidence)` Creates a copy with updated ResolutionEvidence.
`ColumnSource`	`withFieldPath(FieldPath newFieldPath)` Creates a copy with a field path for deep/record field access.
`ColumnSource`	`withFieldPath(FieldPath newFieldPath, String newEvidence)` Creates a copy with field path and updated evidence.
`ColumnSource`	`withFieldPath(List<String> segments)` Creates a copy with a field path from a list of segments.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - ColumnSource
```
public ColumnSource(INamespace sourceNamespace,
                    String exposedName,
                    TParseTreeNode definitionNode,
                    double confidence,
                    String evidence)
```
  - ColumnSource
```
public ColumnSource(INamespace sourceNamespace,
                    String exposedName,
                    TParseTreeNode definitionNode,
                    double confidence,
                    String evidence,
                    TTable overrideTable)
```
  - ColumnSource
```
public ColumnSource(INamespace sourceNamespace,
                    String exposedName,
                    TParseTreeNode definitionNode,
                    double confidence,
                    String evidence,
                    TTable overrideTable,
                    List<TTable> candidateTables)
```
  - ColumnSource
```
public ColumnSource(INamespace sourceNamespace,
                    String exposedName,
                    TParseTreeNode definitionNode,
                    double confidence,
                    String evidence,
                    TTable overrideTable,
                    List<TTable> candidateTables,
                    ResolutionEvidence evidenceDetail)
```
    Full constructor with all fields including ResolutionEvidence.
  - ColumnSource
```
public ColumnSource(INamespace sourceNamespace,
                    String exposedName,
                    TParseTreeNode definitionNode,
                    double confidence,
                    String evidence,
                    TTable overrideTable,
                    List<TTable> candidateTables,
                    ResolutionEvidence evidenceDetail,
                    FieldPath fieldPath)
```
    Full constructor with all fields including ResolutionEvidence and FieldPath.
    
    Parameters:
    
    sourceNamespace - The namespace where this column is exposed
    
    exposedName - The name by which this column is exposed
    
    definitionNode - The AST node where this column is defined
    
    confidence - Confidence score [0.0, 1.0]
    
    evidence - Evidence string for this resolution
    
    overrideTable - Override table for traced columns
    
    candidateTables - Candidate tables for ambiguous columns
    
    evidenceDetail - Structured evidence detail
    
    fieldPath - Field path for deep/record field access
  - ColumnSource
```
public ColumnSource(INamespace sourceNamespace,
                    String exposedName,
                    TParseTreeNode definitionNode,
                    ResolutionEvidence evidenceDetail)
```
    Constructor with ResolutionEvidence (preferred for new code).
  - ColumnSource
```
public ColumnSource(INamespace sourceNamespace,
                    String exposedName,
                    TParseTreeNode definitionNode,
                    ResolutionEvidence evidenceDetail,
                    TTable overrideTable)
```
    Constructor with ResolutionEvidence and override table.
  - ColumnSource
```
public ColumnSource(INamespace sourceNamespace,
                    String exposedName,
                    TParseTreeNode definitionNode)
```
    Constructor for definite matches (confidence = 1.0)
- Method Detail
  - getSourceNamespace
```
public INamespace getSourceNamespace()
```
  - getExposedName
```
public String getExposedName()
```
  - getDefinitionNode
```
public TParseTreeNode getDefinitionNode()
```
  - getDefinitionLocation
```
public SourceLocation getDefinitionLocation()
```
  - getConfidence
```
public double getConfidence()
```
  - getEvidence
```
public String getEvidence()
```
  - getEvidenceDetail
```
public ResolutionEvidence getEvidenceDetail()
```
    Get the structured evidence detail for this resolution.
    This is the preferred way to access resolution evidence as it provides:
    - Type-safe evidence type (enum)
    - Confidence weight with clear semantics
    - Source location for traceability
    - Human-readable messages
    Returns:
    
    The structured evidence detail, or null if not available
  - getEvidenceType
```
public EvidenceType getEvidenceType()
```
    Get the evidence type from the structured evidence detail. Convenience method for common use cases.
    
    Returns:
    
    The evidence type, or null if no evidence detail
  - hasDefiniteEvidence
```
public boolean hasDefiniteEvidence()
```
    Check if this resolution has definite evidence (not inferred). Definite evidence comes from DDL, metadata, or explicit definitions.
    
    Returns:
    
    true if evidence is definite
  - getFinalTable
```
public TTable getFinalTable()
```
    Get the final physical table this column originates from after tracing through all subqueries and CTEs.
    Semantic Difference: getFinalTable() vs TObjectName.getSourceTable()
    - getFinalTable() (this method): The final physical table after recursively tracing through all subqueries and CTEs. Use this for data lineage.
    - TObjectName.getSourceTable(): The immediate source in the current scope. For a column from a subquery, this points to the subquery's TTable itself.
    Example
```
 SELECT title FROM (SELECT * FROM books) sub

 For the 'title' column in outer SELECT:
 - TObjectName.getSourceTable() → TTable for subquery 'sub' (immediate source)
 - ColumnSource.getFinalTable() → TTable for 'books' (final physical table)
 
```
    For calculated columns in subqueries (expressions like START_DT - x AS alias), this returns null because such calculated columns don't originate from a physical table - they are derived values computed in the subquery.
    
    For aliased columns in subqueries (e.g., SELECT t.id AS col1 FROM my_table t), this traces through the alias to find the physical table, because the data still originates from the physical table even though the column has been renamed.
    
    Note: For CTEs, calculated columns ARE the CTE's own columns, so they trace to the CTE itself (handled by CTENamespace.getFinalTable()).
    Returns:
    
    The physical table, or null if unable to determine or if calculated in subquery
    
    See Also:
    
    TObjectName.getSourceTable()
  - getFinalColumnName
```
public String getFinalColumnName()
```
    Get the original column name in the physical table when this column is an alias.
    When a column is aliased in a subquery (e.g., SELECT t.id AS col1), the exposed name is col1 but the original column in the physical table is id. This method returns id so callers can pair the correct column name with the physical table returned by getFinalTable().
    
    For multi-level aliases (e.g., SELECT ADCS_MSISDN FROM (SELECT MSISDN AS ADCS_MSISDN FROM t) sub), this recursively traces through all levels to find the original column name (MSISDN).
    
    Returns:
    
    The original column name if this is an alias, or null if not an alias or unable to determine
  - getAllFinalTables
```
public List<TTable> getAllFinalTables()
```
    Get all physical tables that this column might originate from.
    For columns from UNION queries, this returns tables from ALL branches, not just the first one. This is essential for proper lineage tracking where a column like actor_id in a UNION query should be linked to actor.actor_id, actor2.actor_id, actor3.actor_id.
    
    For regular single-table sources, this returns a single-element list with the same table as getFinalTable().
    
    Returns:
    
    List of all physical tables, or empty list if unable to determine
  - isCalculatedColumn
```
public boolean isCalculatedColumn()
```
    Check if this column source represents a calculated expression.
    A column is calculated if its definition is a TResultColumn with a non-simple expression (not a direct column reference or star).
    
    For inferred columns (via star expansion), we trace back to the source CTE/subquery to check if the original column is calculated.
    
    Returns:
    
    true if this is a calculated column
  - isColumnAlias
```
public boolean isColumnAlias()
```
    Check if this column source represents a column alias (renamed column).
    A column is an alias if it's a simple column reference in a subquery that has been given a different name via AS or NAMED. For example:
    - SELECT col AS alias FROM table - alias is different from col
    - SELECT col (NAMED alias) FROM table - Teradata NAMED syntax
    - SELECT alias = col FROM table - SQL Server proprietary syntax
    Column aliases are traced through in getFinalTable() to find the physical table the data originates from, since the alias only renames the column but the data still comes from the physical table.
    Returns:
    
    true if this is a column alias with a different name than the original
  - isCTEExplicitColumn
```
public boolean isCTEExplicitColumn()
```
    Check if this column is a CTE explicit column with a different name than the underlying column.
    A CTE explicit column is one defined in the CTE's column list that maps to a different column name in the CTE's SELECT list. For example:
```
 WITH cte(c1, c2) AS (SELECT id, name FROM users)
 SELECT c1 FROM cte  -- c1 maps to 'id', names differ
 
```
    CTE explicit columns should NOT trace to base tables because the explicit column name (c1) doesn't exist as an actual column in the base table (users).
    Returns:
    
    true if this is a CTE explicit column with a different name
  - getOverrideTable
```
public TTable getOverrideTable()
```
    Get the override table, if set.
  - getCandidateTables
```
public List<TTable> getCandidateTables()
```
    Get the candidate tables for ambiguous columns.
    When a column could come from multiple tables (e.g., SELECT * FROM t1, t2), this returns all possible source tables. End users can iterate through this list to understand all potential sources for the column.
    
    Returns:
    
    List of candidate tables, or empty list if not ambiguous
  - isAmbiguous
```
public boolean isAmbiguous()
```
    Check if this column has multiple candidate tables (is ambiguous).
    
    Returns:
    
    true if there are multiple candidate tables
  - getFieldPath
```
public FieldPath getFieldPath()
```
    Get the field path for deep/record field access.
    When a column reference includes field access beyond the base column, this returns the field path. For example, in customer.address.city, if base column is customer, this returns a FieldPath with segments ["address", "city"].
    
    Returns:
    
    The field path, or null if no field access
  - hasFieldPath
```
public boolean hasFieldPath()
```
    Check if this column source has a field path (deep/record field access).
    
    Returns:
    
    true if a non-empty field path exists
  - isStructFieldAccess
```
public boolean isStructFieldAccess()
```
    Check if this is a struct field access (has evidence "struct_field_access").
    This is a convenience method for checking if this column source represents a struct/record field dereference operation.
    
    Returns:
    
    true if this is a struct field access
  - isDefinite
```
public boolean isDefinite()
```
    Checks if this is a definite resolution (confidence = 1.0)
  - isInferred
```
public boolean isInferred()
```
    Checks if this is an inferred resolution (confidence < 1.0)
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - withConfidence
```
public ColumnSource withConfidence(double newConfidence,
                                   String newEvidence)
```
    Deprecated. Use withEvidence(ResolutionEvidence) instead
    
    Creates a copy with updated confidence and evidence. Used when merging or updating inference results.
  - withEvidence
```
public ColumnSource withEvidence(ResolutionEvidence newEvidence)
```
    Creates a copy with updated ResolutionEvidence. This is the preferred method for updating evidence in new code.
    
    Parameters:
    
    newEvidence - The new evidence detail
    
    Returns:
    
    A new ColumnSource with updated evidence
  - withCandidateTables
```
public ColumnSource withCandidateTables(List<TTable> candidates)
```
    Creates a copy with candidate tables. Used when a column could come from multiple tables.
  - withFieldPath
```
public ColumnSource withFieldPath(FieldPath newFieldPath)
```
    Creates a copy with a field path for deep/record field access.
    This method is used when resolving struct/record field access patterns like customer.address.city. The base column is preserved as the exposedName, and the field path captures the remaining segments.
    
    Parameters:
    
    newFieldPath - The field path segments (beyond the base column)
    
    Returns:
    
    A new ColumnSource with the field path set
  - withFieldPath
```
public ColumnSource withFieldPath(List<String> segments)
```
    Creates a copy with a field path from a list of segments.
    Convenience method for creating a ColumnSource with a field path from a list of string segments.
    
    Parameters:
    
    segments - The field path segments
    
    Returns:
    
    A new ColumnSource with the field path set
  - withFieldPath
```
public ColumnSource withFieldPath(FieldPath newFieldPath,
                                  String newEvidence)
```
    Creates a copy with field path and updated evidence.
    This method is used when resolving struct field access, combining both the field path and the struct_field_access evidence marker.
    
    Parameters:
    
    newFieldPath - The field path segments
    
    newEvidence - The evidence string (e.g., "struct_field_access")
    
    Returns:
    
    A new ColumnSource with field path and evidence updated
  - isColumnInTableDdl
```
public static boolean isColumnInTableDdl(TTable table,
                                         String columnName)
```
    Check if a column exists in a table's DDL definition.
    This method checks the table's column definitions (from CREATE TABLE statements parsed in the same script) to verify if the column name is defined.
    
    Parameters:
    
    table - The table to check
    
    columnName - The column name to look for
    
    Returns:
    
    true if the column exists in the table's DDL, false if not found or no DDL available
  - hasTableDdl
```
public static boolean hasTableDdl(TTable table)
```
    Check if a table has DDL metadata available (from CREATE TABLE in same script).
    
    Parameters:
    
    table - The table to check
    
    Returns:
    
    true if DDL metadata is available for this table
  - getDdlVerificationStatus
```
public static int getDdlVerificationStatus(TTable table,
                                           String columnName)
```
    Check DDL verification status for a candidate table.
    Returns a tri-state result:
    - 1 = Column exists in table's DDL
    - 0 = Column NOT found in table's DDL (DDL available but column missing)
    - -1 = Cannot verify (no DDL available for this table)
    Parameters:
    
    table - The candidate table to check
    
    columnName - The column name to verify
    
    Returns:
    
    DDL verification status: 1 (exists), 0 (not found), -1 (no DDL)
  - getCandidateTableDdlStatus
```
public Map<TTable,Integer> getCandidateTableDdlStatus()
```
    Get DDL verification status for all candidate tables.
    Returns a map from each candidate table to its DDL verification status:
    - 1 = Column exists in table's DDL
    - 0 = Column NOT found in table's DDL
    - -1 = Cannot verify (no DDL available)
    Returns:
    
    Map of candidate tables to their DDL verification status, or empty map if no candidates

Class ColumnSource

Constructor Summary

Method Summary

Methods inherited from class Object

Constructor Detail

ColumnSource

ColumnSource

ColumnSource

ColumnSource

ColumnSource

ColumnSource

ColumnSource

ColumnSource

Method Detail

getSourceNamespace

getExposedName

getDefinitionNode

getDefinitionLocation

getConfidence

getEvidence

getEvidenceDetail

getEvidenceType

hasDefiniteEvidence

getFinalTable

Semantic Difference: getFinalTable() vs TObjectName.getSourceTable()

Example

getFinalColumnName

getAllFinalTables

isCalculatedColumn

isColumnAlias

isCTEExplicitColumn

getOverrideTable

getCandidateTables

isAmbiguous

getFieldPath

hasFieldPath

isStructFieldAccess

isDefinite

isInferred

toString

withConfidence

withEvidence

withCandidateTables

withFieldPath

withFieldPath

withFieldPath

isColumnInTableDdl

hasTableDdl

getDdlVerificationStatus

getCandidateTableDdlStatus