SqllrObservations (General SQL Parser Java Library Core 4.2.19 API)

Object
- gudusoft.gsqlparser.dlineage.dataflow.model.SqllrObservations

```
public final class SqllrObservations
extends Object
```
What one dlineage analysis observed while it bound names, recorded for the SQL-LR producer (gudusoft.gsqlparser.lineage.v2.producer, plan docs/designs/data-lineage/06-sqllr-m2-producer-plan-zh.md).
Internal API: the producer creates a recorder, gives it to the analyzer it runs, and reads it on the analysis thread before dispose(). The hooks only record: they never change the model, allocate a model id or call a resolver, so legacy output is byte-identical whether a recorder is present or not. With no recorder bound, every hook is one volatile read.

A recorder made with producerMode = true also switches the analysis into SQL-LR production: parsers never guess between candidates, every input is its own unit with its text unchanged, and a failed top-level statement is isolated instead of ending the analysis. Only the producer makes such a recorder; an observe-only recorder (SqllrObservations()) changes nothing.

Not thread-safe: one recorder belongs to one analysis on one thread.

Since:

4.2.17

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`SqllrObservations.DerivedRecord` A statement of dynamic SQL text the analysis parsed, with the statement whose analysis parsed it (its site).
`static class`	`SqllrObservations.ElementRecord` One relationship element added as a source or set as a target, with the reference it was added under.
`static interface`	`SqllrObservations.FreezeHook` Called at the end of `freeze(gudusoft.gsqlparser.dlineage.dataflow.model.ModelBindingManager)`: the SQL-LR producer projects what it reads there (plan 09, slice 1b).
`static class`	`SqllrObservations.FrozenRelation` A relationship as it stood when the analysis finished, before output materialization changed the model.
`static class`	`SqllrObservations.ReferenceRecord` One name reference the analysis processed for a target, whether or not it added a source: a reference that bound nothing (an ambiguous or unknown name) is still an attempted read.
`static class`	`SqllrObservations.StatementRecord` One analysed top-level statement and how its analysis ended.
`static class`	`SqllrObservations.UnitRecord` One parsed unit: its top-level statements and syntax errors, copied when it was parsed.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`DECISION_ARRAY_AGG_ORDER_BY_FIRST_TABLE` An ARRAY_AGG ORDER BY key linked to the first FROM item, written back to the parse tree.
`static String`	`DECISION_FIRST_TABLE_WITH_COLUMN` A column bound to the first FROM item that lists a column of its name (`ModelBindingManager.getTable`).
`static String`	`DECISION_GUESS_TABLE` A column bound to any table the run has seen with a column of its name (`guessTable`).
`static String`	`DECISION_ORPHAN_FIRST_TABLE` An orphan column linked to the first FROM item (`Option.linkOrphanColumnToFirstTable`).
`static String`	`DECISION_ORPHAN_PSEUDO_TABLE` An orphan column with a qualified prefix linked to a pseudo table named after the prefix.
`static String`	`DECISION_UNNEST_FIRST_TABLE` The array an UNNEST reads taken from the first FROM item.

Constructor Summary

Constructors
Constructor and Description

SqllrObservations()
An observe-only recorder: the analysis behaves exactly as without it.

SqllrObservations(boolean producerMode)

Constructors
Constructor and Description
`SqllrObservations()` An observe-only recorder: the analysis behaves exactly as without it.
`SqllrObservations(boolean producerMode)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`beginStatement(TCustomSqlStatement statement)` A top-level statement's analysis starts.
`void`	`beginUnit(String unitKey)` The analyzer starts the statements of the unit with this key.
`void`	`checkInjectedFailure(TCustomSqlStatement statement, boolean before)` Called by the analyzer: throws the injected failure for this statement and point, if any.
`void`	`close()` Stops recording; the hooks of other analyses no longer pay for this recorder.
`void`	`closeFrame(int frame)` Closes the frame and any frame a failed nested analysis left open above it.
`static SqllrObservations`	`current()` The recorder of the analysis bound to the current thread, or `null`.
`void`	`decision(String id, TObjectName reference, Object selected, String reason)` The analysis decided a binding by a fallback (plan 06, Section 3.3): called before it acts on the decision, so the reference is recorded as it stood.
`void`	`derivedStatement(TCustomSqlStatement statement, TCustomSqlStatement site)` A statement of dynamic SQL text is analysed, inside the analysis of `site`.
`void`	`endStatement(TCustomSqlStatement statement, Throwable failure)` A top-level statement's analysis ended, normally (`failure == null`) or with an exception.
`void`	`enterStatement(TCustomSqlStatement statement)` The analysis enters a statement: every statement it analyses, nested and dynamic ones included.
`void`	`freeze(ModelBindingManager manager)` Freezes the runtime graph when the analysis is complete and before output materialization changes it (`SELECT *` links, inferred sources).
`List<SqllrObservations.DerivedRecord>`	`getDerived()` The statements of dynamic SQL texts, in analysis order.
`List<SqllrObservations.ElementRecord>`	`getElements()` Every recorded element, in recording order.
`Throwable`	`getFreezeHookFailure()` What the freeze hook threw, or `null`.
`List<ResultColumn>`	`getFrozenColumns(ResultSet resultSet)` The columns of a result set at the freeze, or `null` when no frozen relationship reaches the result set.
`List<SqllrObservations.FrozenRelation>`	`getFrozenRelations()` The relationships at the freeze, in creation order; `null` before `freeze(gudusoft.gsqlparser.dlineage.dataflow.model.ModelBindingManager)`.
`List<ResultSet>`	`getFrozenResultSets()` Every result set at the freeze (the model's, then any only a relationship reaches), in creation order.
`List<SqllrObservations.ReferenceRecord>`	`getReferences()` Every reference the analysis read for a target, in recording order.
`SqllrSnapshot`	`getSnapshot()` The value snapshot of the analysis (plan 09, Section 3.1), taken at `freeze(gudusoft.gsqlparser.dlineage.dataflow.model.ModelBindingManager)`; `null` before the freeze or when building it failed (`getSnapshotFailure()`).
`String`	`getSnapshotFailure()` Why the snapshot could not be built, or `null`.
`long`	`getSnapshotNanos()` How long building the snapshot's topology at the freeze took, in nanoseconds; -1 when it was not built.
`List<SqllrObservations.StatementRecord>`	`getStatements()` The analysed top-level statements, in the order their analysis started.
`List<Object>`	`getStructFieldColumns()` The field columns `structField(java.lang.Object, gudusoft.gsqlparser.nodes.TResultColumn)` recorded, in the order it first recorded them.
`TResultColumn`	`getStructItem(Object column)` The select item whose STRUCT a field column belongs to, or null.
`List<SqllrObservations.UnitRecord>`	`getUnits()` The parsed units, in analysis order.
`void`	`injectFailure(String prefix, boolean before)` Tests only: make the analysis of the first top-level statement whose text starts with `prefix` fail, before its analysis (`before`) or after it changed the model.
`void`	`injectFailureDuring(String prefix, boolean error)` Tests only: make the analysis of the first top-level statement whose text starts with `prefix` fail inside the analysis, when it records its first relationship element; with `error` the failure is a `java.lang.Error`.
`boolean`	`isFrozen()`
`boolean`	`isProducerMode()` Whether the bound analysis runs as SQL-LR production rather than only being observed.
`int`	`openFrame()` Opens a barrier: elements added until it closes carry no reference unless an inner frame names one.
`int`	`openFrame(Object target)` Opens a frame for a loop that reads references for `target`; pass the result to `reference(int, gudusoft.gsqlparser.nodes.TObjectName)` and `closeFrame(int)`.
`void`	`parsedUnit(TGSqlParser parser, int parseResult)` The analyzer parsed the unit it announced with `beginUnit(java.lang.String)`.
`void`	`reference(int frame, TObjectName name)` The reference the frame is processing from now on; recorded as an attempted read of the frame's target.
`void`	`registerUnit(String unitKey, int index)` The analyzer keyed input `index` as `unitKey`.
`void`	`setFreezeHook(SqllrObservations.FreezeHook hook)` The producer's hook, run once when the analysis freezes; a failure is kept, never thrown into the analysis.
`void`	`structField(Object column, TResultColumn item)` A column the analysis built for a field of a STRUCT that a select item constructs.

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

- Field Detail
  - DECISION_ORPHAN_FIRST_TABLE
```
public static final String DECISION_ORPHAN_FIRST_TABLE
```
    An orphan column linked to the first FROM item (Option.linkOrphanColumnToFirstTable).
    
    See Also:
    
    Constant Field Values
  - DECISION_ORPHAN_PSEUDO_TABLE
```
public static final String DECISION_ORPHAN_PSEUDO_TABLE
```
    An orphan column with a qualified prefix linked to a pseudo table named after the prefix.
    
    See Also:
    
    Constant Field Values
  - DECISION_ARRAY_AGG_ORDER_BY_FIRST_TABLE
```
public static final String DECISION_ARRAY_AGG_ORDER_BY_FIRST_TABLE
```
    An ARRAY_AGG ORDER BY key linked to the first FROM item, written back to the parse tree.
    
    See Also:
    
    Constant Field Values
  - DECISION_UNNEST_FIRST_TABLE
```
public static final String DECISION_UNNEST_FIRST_TABLE
```
    The array an UNNEST reads taken from the first FROM item.
    
    See Also:
    
    Constant Field Values
  - DECISION_FIRST_TABLE_WITH_COLUMN
```
public static final String DECISION_FIRST_TABLE_WITH_COLUMN
```
    A column bound to the first FROM item that lists a column of its name (ModelBindingManager.getTable).
    
    See Also:
    
    Constant Field Values
  - DECISION_GUESS_TABLE
```
public static final String DECISION_GUESS_TABLE
```
    A column bound to any table the run has seen with a column of its name (guessTable).
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - SqllrObservations
```
public SqllrObservations()
```
    An observe-only recorder: the analysis behaves exactly as without it.
  - SqllrObservations
```
public SqllrObservations(boolean producerMode)
```
    Parameters:
    
    producerMode - true only for the SQL-LR producer's own analysis, which this switches into production (see the class comment)
- Method Detail
  - isProducerMode
```
public boolean isProducerMode()
```
    Whether the bound analysis runs as SQL-LR production rather than only being observed.
  - close
```
public void close()
```
    Stops recording; the hooks of other analyses no longer pay for this recorder. Idempotent.
  - current
```
public static SqllrObservations current()
```
    The recorder of the analysis bound to the current thread, or null.
  - openFrame
```
public int openFrame()
```
    Opens a barrier: elements added until it closes carry no reference unless an inner frame names one.
  - openFrame
```
public int openFrame(Object target)
```
    Opens a frame for a loop that reads references for target; pass the result to reference(int, gudusoft.gsqlparser.nodes.TObjectName) and closeFrame(int).
  - reference
```
public void reference(int frame,
                      TObjectName name)
```
    The reference the frame is processing from now on; recorded as an attempted read of the frame's target.
  - closeFrame
```
public void closeFrame(int frame)
```
    Closes the frame and any frame a failed nested analysis left open above it.
  - enterStatement
```
public void enterStatement(TCustomSqlStatement statement)
```
    The analysis enters a statement: every statement it analyses, nested and dynamic ones included.
  - decision
```
public void decision(String id,
                     TObjectName reference,
                     Object selected,
                     String reason)
```
    The analysis decided a binding by a fallback (plan 06, Section 3.3): called before it acts on the decision, so the reference is recorded as it stood. selected is the parse tree node or model object chosen.
  - registerUnit
```
public void registerUnit(String unitKey,
                         int index)
```
    The analyzer keyed input index as unitKey.
  - beginUnit
```
public void beginUnit(String unitKey)
```
    The analyzer starts the statements of the unit with this key.
  - parsedUnit
```
public void parsedUnit(TGSqlParser parser,
                       int parseResult)
```
    The analyzer parsed the unit it announced with beginUnit(java.lang.String).
  - getUnits
```
public List<SqllrObservations.UnitRecord> getUnits()
```
    The parsed units, in analysis order.
  - structField
```
public void structField(Object column,
                        TResultColumn item)
```
    A column the analysis built for a field of a STRUCT that a select item constructs. Observe-only.
  - getStructItem
```
public TResultColumn getStructItem(Object column)
```
    The select item whose STRUCT a field column belongs to, or null.
  - getStructFieldColumns
```
public List<Object> getStructFieldColumns()
```
    The field columns structField(java.lang.Object, gudusoft.gsqlparser.nodes.TResultColumn) recorded, in the order it first recorded them.
  - derivedStatement
```
public void derivedStatement(TCustomSqlStatement statement,
                             TCustomSqlStatement site)
```
    A statement of dynamic SQL text is analysed, inside the analysis of site. Observe-only.
  - getDerived
```
public List<SqllrObservations.DerivedRecord> getDerived()
```
    The statements of dynamic SQL texts, in analysis order.
  - beginStatement
```
public void beginStatement(TCustomSqlStatement statement)
```
    A top-level statement's analysis starts.
  - injectFailure
```
public void injectFailure(String prefix,
                          boolean before)
```
    Tests only: make the analysis of the first top-level statement whose text starts with prefix fail, before its analysis (before) or after it changed the model. Exercises the failure isolation of SQL-LR production.
  - injectFailureDuring
```
public void injectFailureDuring(String prefix,
                                boolean error)
```
    Tests only: make the analysis of the first top-level statement whose text starts with prefix fail inside the analysis, when it records its first relationship element; with error the failure is a java.lang.Error.
  - checkInjectedFailure
```
public void checkInjectedFailure(TCustomSqlStatement statement,
                                 boolean before)
```
    Called by the analyzer: throws the injected failure for this statement and point, if any.
  - endStatement
```
public void endStatement(TCustomSqlStatement statement,
                         Throwable failure)
```
    A top-level statement's analysis ended, normally (failure == null) or with an exception.
  - freeze
```
public void freeze(ModelBindingManager manager)
```
    Freezes the runtime graph when the analysis is complete and before output materialization changes it (SELECT * links, inferred sources). Later hook calls are ignored.
  - getSnapshot
```
public SqllrSnapshot getSnapshot()
```
    The value snapshot of the analysis (plan 09, Section 3.1), taken at freeze(gudusoft.gsqlparser.dlineage.dataflow.model.ModelBindingManager); null before the freeze or when building it failed (getSnapshotFailure()). It holds no live object and stays readable after the analyzer is disposed, from any thread.
  - getSnapshotFailure
```
public String getSnapshotFailure()
```
    Why the snapshot could not be built, or null.
  - setFreezeHook
```
public void setFreezeHook(SqllrObservations.FreezeHook hook)
```
    The producer's hook, run once when the analysis freezes; a failure is kept, never thrown into the analysis.
  - getFreezeHookFailure
```
public Throwable getFreezeHookFailure()
```
    What the freeze hook threw, or null.
  - getSnapshotNanos
```
public long getSnapshotNanos()
```
    How long building the snapshot's topology at the freeze took, in nanoseconds; -1 when it was not built.
  - getFrozenResultSets
```
public List<ResultSet> getFrozenResultSets()
```
    Every result set at the freeze (the model's, then any only a relationship reaches), in creation order.
  - getFrozenColumns
```
public List<ResultColumn> getFrozenColumns(ResultSet resultSet)
```
    The columns of a result set at the freeze, or null when no frozen relationship reaches the result set.
  - getReferences
```
public List<SqllrObservations.ReferenceRecord> getReferences()
```
    Every reference the analysis read for a target, in recording order.
  - isFrozen
```
public boolean isFrozen()
```
  - getFrozenRelations
```
public List<SqllrObservations.FrozenRelation> getFrozenRelations()
```
    The relationships at the freeze, in creation order; null before freeze(gudusoft.gsqlparser.dlineage.dataflow.model.ModelBindingManager).
  - getElements
```
public List<SqllrObservations.ElementRecord> getElements()
```
    Every recorded element, in recording order.
  - getStatements
```
public List<SqllrObservations.StatementRecord> getStatements()
```
    The analysed top-level statements, in the order their analysis started.

Class SqllrObservations

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class Object

Field Detail

DECISION_ORPHAN_FIRST_TABLE

DECISION_ORPHAN_PSEUDO_TABLE

DECISION_ARRAY_AGG_ORDER_BY_FIRST_TABLE

DECISION_UNNEST_FIRST_TABLE

DECISION_FIRST_TABLE_WITH_COLUMN

DECISION_GUESS_TABLE

Constructor Detail

SqllrObservations

SqllrObservations

Method Detail

isProducerMode

close

current

openFrame

openFrame

reference

closeFrame

enterStatement

decision

registerUnit

beginUnit

parsedUnit

getUnits

structField

getStructItem

getStructFieldColumns

derivedStatement

getDerived

beginStatement

injectFailure

injectFailureDuring

checkInjectedFailure

endStatement

freeze

getSnapshot

getSnapshotFailure

setFreezeHook

getFreezeHookFailure

getSnapshotNanos

getFrozenResultSets

getFrozenColumns

getReferences

isFrozen

getFrozenRelations

getElements

getStatements