Implementation:MaterializeInc Materialize Namescore CLI

Overview

The namescore CLI tool calculates the "namescore" of EXPLAIN PLAN output -- the percentage of column references that include name information. It is designed to measure how well the optimizer preserves human-readable column names across plan stages, running by default against all SLT (SQL Logic Test) files in the repository.

The tool is located at misc/python/materialize/cli/namescore.py.

Purpose

In Materialize's query plans, column references take the form #N (positional) or #N{column_name} (named). The namescore metric tracks what fraction of column references carry name annotations, providing a quantitative measure of plan readability.

Column Reference Pattern

The tool uses a regex to identify column references in plan output:

COLUMN_REF_RE = re.compile(
    r"""
    \#[0-9]+({[^}]+})?
    """,
    re.VERBOSE,
)

This matches:

• #0 -- A positional reference without a name (not counted as "named").
• #0{customer_id} -- A positional reference with a name annotation (counted as "named").
• #0{"?column?"} -- A reference with the unknown column placeholder (counted as "named" but also tallied separately as "unknown").

Core Functions

find_slt_files

Walks the $MZ_ROOT/test/sqllogictest directory tree and returns a list of all .slt file paths.

def find_slt_files() -> list[str]:
    slt_files = []
    for root, _dirs, files in os.walk(SLT_ROOT):
        for file in files:
            if file.endswith(".slt"):
                slt_files.append(os.path.join(root, file))
    return slt_files

namescore

Calculates the namescore for a single file, returning a tuple of three integers:

Return Value	Description
named_refs	Count of column references that have name annotations
unknown_cols	Count of references annotated with {"?column?"}
refs	Total count of all column references

def namescore(filename: str) -> tuple[int, int, int]:
    named_refs = 0
    unknown_cols = 0
    refs = 0
    with open(filename) as f:
        content = f.read()
        for match in COLUMN_REF_RE.finditer(content):
            refs += 1
            if match.group(1):
                named_refs += 1
                if match.group(1) == '{"?column?"}':
                    unknown_cols += 1
    return (named_refs, unknown_cols, refs)

CLI Interface

The main function accepts an optional list of test file paths. When no files are specified, it defaults to all .slt files found under $MZ_ROOT/test/sqllogictest.

Arguments

Argument	Required	Description
tests	No	Explicit file paths to analyze; defaults to all SLT files

Output Format

For each file with at least one column reference, the tool prints:

relative/path/to/file.slt: 85.00% (17 / 20; 2 unknown columns)

Files with zero column references are silently skipped (counted in the final summary).

The final summary line reports the aggregate:

Overall namescore: 72.15% (1234 / 1710; 45 unknown columns); 30 files with no column references / 500 total files

Key Source Files

File	Path
Namescore CLI	misc/python/materialize/cli/namescore.py