`````{admonition} **script**
:class: toggle, sn-fixture, sn-fixture-local, sn-unset-margins, sn-block, sn-code-pad, toggle-shown
```{div} sn-pre-code
This section performs operations on the following {fa}`fixture script`:
```
````{div} sn-indent-h-cell-even
```{literalinclude} ../snippets/script/overview-statement-intro.py
:language: python
:lines: 17-17
```
````
```{div} sn-indent-h-cell-text
Where `path` ({class}`pathlib.Path` or {class}`str`) is a full path to
[overview.sql](script/statements/quick-intro).
```
```{div} sn-snippet-h, sn-indent-h-cell
[{fa}`file-code-o` overview.sql](../snippets.md#overviewsql)
```
````{div} sn-indent-h-cell-even
```{literalinclude} ../snippets/script/overview.sql
:language: sql
:lines: 3-32
:emphasize-lines: 1, 6, 17, 20, 22, 24, 30
```
````
`````
```{div} sn-dedent-v-b-h-m
*The intent of the following taxonomy is to define a standard such that the
name for a given statement is:*
```
```{div} sn-bold-list
1. Constructed from attributes that can be unambiguously parsed from
a piece of raw sql
1. Structured such that user *provided* names can be easily
implemented and loosely parsed into the same set of attributes
as those *generated* from (**1**)
```
Every statement has a {class}`~snowmobile.core.name.Name` with a set of
underlying properties that are used by the rest of the API; for each property,
there is a *generated* (**_ge**) and *provided* (**_pr**) attribute from
which its final value is sourced.
(script/note1)=
*Generated* attributes are populated for all st, whereas only those
with a name specified in a [tag](#tags) have populated *provided* attributes;
consequently, a *provided* value takes precedent over its *generated* counterpart.
````{admonition} Example: **nm**
:class: sn-example
```{div} sn-pre-code-s
The {class}`~snowmobile.core.name.Name.nm` value for a given statement will
be equivalent to its {attr}`~snowmobile.core.name.Name.nm_pr` if present and
its {attr}`~snowmobile.core.name.Name.nm_ge` otherwise.
```
````
(script/statement/nm)=
This resolution order is repeated across the underlying
components of {class}`~snowmobile.core.name.Name.nm`, documented in the
following sections.
`````{admonition} **s1** & **s4**
:class: toggle, toggle-shown, sn-fixture, sn-fixture-local, sn-block, sn-increase-margin-v-container, sn-code-pad
The below statements, `s1` and `s4`, from
[{fa}`fixture script`](script/statements/quick-intro) are used throughout the
remaining examples in [this section](#statement-names).
```{literalinclude} ../snippets/script/overview-statement-names.py
:language: python
:lines: 21-22
:emphasize-lines: 4-5
```
`````
% (nm)
##### ***nm***
````{div} sn-def, sn-dedent-v-t-container-neg, sn-linear-gradient-background, sn-def-container-side-border
```{div} sn-block-indented-h
>{anchor}{delimiter}{desc}
```
{attr}`~snowmobile.core.name.Name.anchor`\
*what operation is a statement performing*
on what kind of object is it operating
{attr}`~snowmobile.core.cfg.script.Core.delimiter`
```{div} sn-multiline-def
*a*
configured value
*with which to delimit the {attr}`~snowmobile.core.name.Name.anchor` and
{attr}`~snowmobile.core.name.Name.desc`*
```
{attr}`~snowmobile.core.name.Name.desc`\
*A free-form piece of text associated with the statement*
````
% (-)
``````{tabbed} -
:class-content: sn-light-shadow
{attr}`~snowmobile.core.name.Name.nm` is the highest-level accessor
for a {class}`~snowmobile.core.statement.Statement`.
Its values for
s1 & s4
(for example) can be inspected with:
```{literalinclude} ../snippets/script/overview-statement-names.py
:language: python
:lines: 24-25
```
``````
``````{tabbed} nm_pr
:class-content: sn-light-shadow
:class-label: sn-rm-background
In determining the {attr}`~snowmobile.core.name.Name.nm`
for
s1 specifically, [{fa}`fixture script`](script/statements/quick-intro)
is considering the following two lines of [overview.sql](script/statements/quick-intro):
```{literalinclude} ../snippets/script/overview.sql
:language: sql
:lines: 21-22
```
```{div} sn-post-code
Each of these two lines above is the respective source for *provided* and
*generated* information about the statement called out
in
Example: **nm**
, the underlying values for which can be inspected in the same way:
```
```{literalinclude} ../snippets/script/overview-statement-names.py
:language: python
:lines: 36-46
```
``````
% (anchor =======================================================)
##### ***anchor***
````{div} sn-def, sn-dedent-v-t-container-neg, sn-linear-gradient-background, sn-def-container-side-border
```{div} sn-block-indented-h
>{kw} {obj}
```
{attr}`~snowmobile.core.name.Name.kw`\
*the literal first sql keyword the statement contains*
{attr}`~snowmobile.core.name.Name.obj`\
*the in-warehouse object found in the first line of the statement*
````
``````{tabbed} -
:class-content: sn-light-shadow
{attr}`~snowmobile.core.name.Name.anchor` represents all text to the left of
the first {attr}`~snowmobile.core.cfg.script.Core.delimiter` and when
[*generated*](#statement-names) will fit the above structure to a varying
degree depending on the sql being parsed and configurations in
[](./snowmobile_toml.md).
For
s1 & s4
:
```{literalinclude} ../snippets/script/overview-statement-names.py
:language: python
:lines: 30-31
```
``````
% (kw ===========================================================)
(script-kw)=
##### ***kw***
``````{tabbed} -
:class-content: sn-light-shadow
{attr}`~snowmobile.core.name.Name.kw` is the literal first *keyword*
within the [command](https://docs.snowflake.com/en/sql-reference/sql-all.html)
being executed by a statement's sql.
For
s1 & s4:
```{literalinclude} ../snippets/script/overview-statement-names.py
:language: python
:lines: 59-60
```
``````
``````{tabbed} keyword-exceptions
:class-content: sn-light-shadow
The {ref}`keyword-exceptions
` section in the
{ref}`[sql] ` block of
{ref}`snowmobile-ext.toml `
enables
specifying an alternate keyword for a literal keyword parsed from a statement's
sql; alternate keywords will populate the statement's
{attr}`~snowmobile.core.name.Name.kw_ge` as opposed to the literal keyword
identified at the start of the statement:
```toml
[sql.keyword-exceptions]
"with" = "select"
```
The default included above is the reason that the
{attr}`~snowmobile.core.name.Name.kw` for both the following statements is `select` as opposed to `select` and `with` respectively:
```{literalinclude} ../snippets/script/keyword_exceptions.sql
:language: sql
:lines: 3-10
```
``````
% (obj ==========================================================)
(script-obj)=
##### ***obj***
``````{tabbed} -
:class-content: sn-light-shadow
{attr}`~snowmobile.core.name.Name.obj` is determined by a case-insensitive,
full ('word-boundaried') search through the **first** line of a statement's
sql for a match within a pre-defined set of values.
``````
``````{tabbed} named-objects
:class-content: sn-light-shadow
The values for which a match is checked are configured in the
{ref}`named-objects ` section within the {ref}`[sql] `
block of {ref}`snowmobile-ext.toml`,
included below.
Matching is peformed against values in the **literal** order as they are
configured in {ref}`snowmobile-ext.toml`
until a match is found or the list is exhausted; it is enforced that the object
found cannot be equal to the {attr}`~snowmobile.core.name.Name.kw`
for the statement.
```{code-block} toml
named-objects = [
# 'grant' statements "select",
"all",
"drop",
# base objects
"temp table",
"transient table",
"table",
"view",
"schema",
"warehouse",
"file format",
# plural bases
"tables",
"views",
"schemas",
]
```
````{admonition} Note
:class: note, toggle, toggle-shown, sn-rm-t-m-code, sn-increase-margin-v-container
The above order is as such so that table qualifiers for the following three
(types of) statements are reflected in the
{attr}`~snowmobile.core.name.Name.obj` for each.
```sql
-- obj = 'table'
create table any_table as
select 1 as any_col;
-- obj = 'transient table'
create transient table any_table2 as
select 1 as any_col;
-- obj = 'temp table'
create temp table any_table3 as
select 1 as any_col;
```
````
``````
``````{tabbed} generic-anchors
:class-content: sn-light-shadow
A mapping of sql keywords to generic anchor names can be configured in the
{ref}`generic-anchors` block within the {ref}`[sql] `
section of {ref}`snowmobile-ext.toml`,
included below.
```{code-block} toml
[sql.generic-anchors]
"select" = "select data"
"set" = "set param"
"unset" = "unset param"
"insert" = "insert into"
"delete" = "delete from"
```
``````
% (delimiter ====================================================)
(script-delimiter)=
##### ***delimiter***
``````{tabbed} -
:class-content: sn-light-shadow
{attr}`~snowmobile.core.cfg.script.Core.delimiter` is a literal constant specified
in the `description-delimiter` field within the
{ref}`[script.patterns.core]` section
of [](./snowmobile_toml.md), the value for which can be accessed directly off
with:
```{literalinclude} ../snippets/script/overview-statement-names.py
:language: python
:lines: 33-33
```
``````
% (desc =========================================================)
(script-desc)=
##### ***desc***
`````{tabbed} -
:class-content: sn-light-shadow
{attr}`~snowmobile.core.name.Name.desc` is a free-form text field loosely
intended to be short-hand *description* for the statement.
The **generated** description for a statement,
{attr}`~snowmobile.core.name.Name.desc_ge`, is a concatenation of a constant
prefix and its index position within the script.
The prefix used is configurable in the `description-index-prefix` field within
the {ref}`[script.patterns.core]`
section of [](./snowmobile_toml.md), the value for which can be accessed
directly off
with:
```python
print(sn.cfg.script.patterns.core.prefix) #> s
```
The **provided** description for a statement,
{attr}`~snowmobile.core.name.Name.desc_pr`, is all text to the right
of the first *character* found matching the {ref}`script-delimiter`
within a statement's {attr}`~snowmobile.core.name.Name.nm_pr`.
`````
`````{tabbed} using *desc-is-simple*
:class-content: sn-light-shadow
```{admonition} Warning
:class: warning, sn-inherit-overflow
The functionality outlined below is experimental and not under test.
```
Using parsed values for the {attr}`~snowmobile.core.name.Name.obj_ge`
and {attr}`~snowmobile.core.name.Name.desc_ge`
can be enabled by setting the {ref}`desc-is-simple` field to
`true` in {ref}`snowmobile-ext.toml` or by
modifying the attribute's value on an instance of
.
In the case of [{fa}`fixture script`](script/statements/quick-intro), this looks
like:
```{literalinclude} ../snippets/script/overview-statement-names.py
:language: python
:lines: 64-68
```
````{div} sn-output2
```{literalinclude} ../snippets/script/overview-statement-names.py
:language: python
:lines: 71-79
```
````
`````