SqlFragment (General SQL Parser Java Library Core 4.2.9 API)

Object
- gudusoft.gsqlparser.dlineage.dynamicsql.SqlFragment

```
public final class SqlFragment
extends Object
```
One provenance-tagged fragment of a materialized dynamic-SQL string.
A materialized string is an ordered fragment sequence whose concatenated text equals the rendered SQL exactly. Each fragment is either:
- SqlFragment.Kind.LITERAL — text proven to be the exact runtime characters: a string literal, or the output of a transform proven byte-exact for the vendor;
- SqlFragment.Kind.HOLE — text standing in for a value the evaluator could not prove exactly: an unbound variable's own token, an unfoldable expression's placeholder, or the output of a transform that is folded for display but NOT proven byte-exact (SqlFragment.HoleOrigin.INEXACT_TRANSFORM).
Consumers (the per-edge publication proof, design doc dynamic-sql-fragment-provenance-design.md) must treat every HOLE as arbitrary runtime text; no lineage evidence may rest on HOLE characters. The legacy SqlStringValue.state/text contract is unchanged — fragments are additional provenance carried alongside it.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`SqlFragment.HoleOrigin` Why a HOLE exists — which producer limitation created it.
`static class`	`SqlFragment.Kind` Fragment class: exact literal text vs.

Field Summary

Fields
Modifier and Type	Field and Description
`SqlFragment.Kind`	`kind`
`SqlFragment.HoleOrigin`	`origin` HOLE only: why the hole exists; null for LITERAL.
`String`	`originName` HOLE only: the variable/function/expression name that caused it; may be null.
`String`	`reason` HOLE only: human-readable cause; null for LITERAL.
`int`	`sourceEndColumn`
`int`	`sourceEndLine`
`long`	`sourceEndOffset`
`int`	`sourceStartColumn`
`int`	`sourceStartLine` The same origin span as line / column: 1-based, end-exclusive end column, in the coordinate system of `TSourceToken.lineNo / columnNo`.
`long`	`sourceStartOffset` Source offsets, end-exclusive, of the fragment's origin in the analyzed text: for a LITERAL the seeding expression; for a HOLE the place the value was last defined — the assignment target of a query-assigned or flow-dependent variable, the declaration of an unbound parameter or of a declared-but-unassigned variable, otherwise the reference that produced the hole.
`String`	`text` Exact rendered text this fragment contributes to the materialized SQL.
`String`	`valueOrigin` Where the value came from.
`boolean`	`valueUnknown` HOLE only: true when the hole's runtime VALUE is unknown (an unbound variable, or a transform applied to one).

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`hasSourceSpan()` True when the origin span is known in line / column form.
`static SqlFragment`	`hole(String renderedText, SqlFragment.HoleOrigin origin, String originName, String reason)` Hole with the default value-knowledge for its origin: every origin except `INEXACT_TRANSFORM` stands in for a value nobody knows; an inexact transform defaults to value-known (computed from literals).
`static SqlFragment`	`hole(String renderedText, SqlFragment.HoleOrigin origin, String originName, String reason, boolean valueUnknown)`
`static SqlFragment`	`hole(String renderedText, SqlFragment.HoleOrigin origin, String originName, String reason, boolean valueUnknown, String valueOrigin, long sourceStartOffset, long sourceEndOffset, int sourceStartLine, int sourceStartColumn, int sourceEndLine, int sourceEndColumn)` Hole with full provenance: the data source its value would come from (`valueOrigin`, may be null) and the origin span in the analyzed text (see `sourceStartOffset` / `sourceStartLine`; pass `-1` for unknown).
`boolean`	`isLiteral()`
`static SqlFragment`	`literal(String text)`
`static SqlFragment`	`literal(String text, String valueOrigin, long sourceStartOffset, long sourceEndOffset)` Exact literal value with its procedure-body seed provenance.
`String`	`toString()`

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

- Field Detail
  - kind
```
public final SqlFragment.Kind kind
```
  - text
```
public final String text
```
    Exact rendered text this fragment contributes to the materialized SQL. Never null.
  - origin
```
public final SqlFragment.HoleOrigin origin
```
    HOLE only: why the hole exists; null for LITERAL.
  - originName
```
public final String originName
```
    HOLE only: the variable/function/expression name that caused it; may be null.
  - reason
```
public final String reason
```
    HOLE only: human-readable cause; null for LITERAL.
  - valueUnknown
```
public final boolean valueUnknown
```
    HOLE only: true when the hole's runtime VALUE is unknown (an unbound variable, or a transform applied to one). False for an INEXACT_TRANSFORM computed entirely from literals, where the value is known and only its byte-exactness against vendor runtime semantics is unproven. The distinction matters to consumers deciding whether a folded identifier is a runtime TEMPLATE (UPPER(@X) — unknown) or merely an unproven rendering of a known name (UPPER('src') — known). Always false for LITERAL fragments.
  - valueOrigin
```
public final String valueOrigin
```
    Where the value came from. LITERAL: the seed of an exact value — null for ordinary SQL string fragments; constant-relation values use a stable description such as INSERT VALUES row 2 of @Source. HOLE: the data source the unknown value would be read from, when the evaluator saw it (dbo.SSF_Entity.Entity for a SqlFragment.HoleOrigin.QUERY_ASSIGNED_VARIABLE); null when unknown.
  - sourceStartOffset
```
public final long sourceStartOffset
```
    Source offsets, end-exclusive, of the fragment's origin in the analyzed text: for a LITERAL the seeding expression; for a HOLE the place the value was last defined — the assignment target of a query-assigned or flow-dependent variable, the declaration of an unbound parameter or of a declared-but-unassigned variable, otherwise the reference that produced the hole. -1 when the origin is not in the analyzed text.
  - sourceEndOffset
```
public final long sourceEndOffset
```
  - sourceStartLine
```
public final int sourceStartLine
```
    The same origin span as line / column: 1-based, end-exclusive end column, in the coordinate system of TSourceToken.lineNo / columnNo. -1 when unknown. Populated for HOLE fragments whose origin is a source node; LITERAL fragments carry offsets only.
  - sourceStartColumn
```
public final int sourceStartColumn
```
  - sourceEndLine
```
public final int sourceEndLine
```
  - sourceEndColumn
```
public final int sourceEndColumn
```
- Method Detail
  - literal
```
public static SqlFragment literal(String text)
```
  - literal
```
public static SqlFragment literal(String text,
                                  String valueOrigin,
                                  long sourceStartOffset,
                                  long sourceEndOffset)
```
    Exact literal value with its procedure-body seed provenance.
  - hole
```
public static SqlFragment hole(String renderedText,
                               SqlFragment.HoleOrigin origin,
                               String originName,
                               String reason)
```
    Hole with the default value-knowledge for its origin: every origin except INEXACT_TRANSFORM stands in for a value nobody knows; an inexact transform defaults to value-known (computed from literals). A transform over a PARTIAL input must use the explicit overload with valueUnknown=true.
  - hole
```
public static SqlFragment hole(String renderedText,
                               SqlFragment.HoleOrigin origin,
                               String originName,
                               String reason,
                               boolean valueUnknown)
```
  - hole
```
public static SqlFragment hole(String renderedText,
                               SqlFragment.HoleOrigin origin,
                               String originName,
                               String reason,
                               boolean valueUnknown,
                               String valueOrigin,
                               long sourceStartOffset,
                               long sourceEndOffset,
                               int sourceStartLine,
                               int sourceStartColumn,
                               int sourceEndLine,
                               int sourceEndColumn)
```
    Hole with full provenance: the data source its value would come from (valueOrigin, may be null) and the origin span in the analyzed text (see sourceStartOffset / sourceStartLine; pass -1 for unknown).
  - hasSourceSpan
```
public boolean hasSourceSpan()
```
    True when the origin span is known in line / column form.
  - isLiteral
```
public boolean isLiteral()
```
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class SqlFragment

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class Object

Field Detail

kind

text

origin

originName

reason

valueUnknown

valueOrigin

sourceStartOffset

sourceEndOffset

sourceStartLine

sourceStartColumn

sourceEndLine

sourceEndColumn

Method Detail

literal

literal

hole

hole

hole

hasSourceSpan

isLiteral

toString