Public API audit

This audit tracks public API changes and records accepted naming decisions before release cuts. No open naming decisions remain for the current release candidate.

Unreleased API additions after 0.5.2

New public surfaces since 0.5.2:

• Sequence helpers: QuackDB.Sequence.next_values/4, QuackDB.Sequence.for_column/4, for_column!/4, and QuackDB.Ecto.column_sequence_name/2.
• Metadata helpers: QuackDB.Meta.primary_keys/3, primary_keys!/3, column_defaults/3, and column_defaults!/3.

• Ecto append option: append_shape: :columns | :rows for direct native append inserts.

Accepted naming decisions for unreleased changes:

• Keep sequence allocation as a small explicit helper instead of adding an Exograph-specific insert_all_with_generated_ids wrapper.
• Use catalog-backed QuackDB.Sequence.for_column/4 when a connection is available; keep QuackDB.Ecto.column_sequence_name/2 as an explicit convention helper for code paths that already know the QuackDB Ecto migration naming convention.
• Keep append_shape explicit and limited to :columns/:rows; do not add :auto until telemetry can justify robust heuristics.

0.5.2 API additions after 0.5.1

New public surfaces since 0.5.1:

• Storage observability: QuackDB.Storage.info/3, info!/3, compression/3, compression!/3, database_size/2, database_size!/2, checkpoint/2, checkpoint!/2, force_checkpoint/2, force_checkpoint!/2, and storage segment/database-size/compression summary structs.
• Catalog metadata: QuackDB.Meta.tables/2, tables!/2, databases/2, databases!/2, table_info/3, table_info!/3, and table/database/column metadata structs.

Accepted naming decisions for 0.5.2 changes:

• Use QuackDB.Storage.info!/2 rather than repeating storage in storage_info!/2.
• Keep storage observability outside QuackDB.Ecto because the same API accepts raw connections and Ecto repos.
• Use compression!/2 for grouped per-table compression summaries instead of a longer compression_summary!/2 name.
• Keep logical catalog helpers in QuackDB.Meta and physical storage/compression helpers in QuackDB.Storage.

0.5.1 API additions after 0.5.0

New public surfaces since 0.5.0:

• DDL options: QuackDB.DDL.create_table/2,3 accepts or_replace: true and QuackDB.DDL.create_table(name, schema, opts) can create a differently named table from an Ecto schema.
• Query profiling: QuackDB.Profile.analyze/4, analyze!/4, explain/4, explain!/4, flatten/1, slowest/2, report/2, and decoded profile/operator structs.

• SQL explain formats: QuackDB.SQL.explain/2 accepts format: :text | :json | :html | :graphviz | :mermaid.

Accepted naming decisions for 0.5.1 changes:

• Keep DDL replacement and schema-copy staging as options/overloads on create_table rather than adding replace_table_as/3 or create_table_like/3.
• Keep query profiling in QuackDB.Profile and reserve telemetry for client-side query/fetch/append timings.
• Decode DuckDB profile JSON into structs, while keeping open-ended extra_info keys as DuckDB returns them.

0.5.0 API additions after 0.4.2

Accepted naming decisions for 0.5.0 changes:

• Keep append opt-in explicit with insert_method: :append; do not add insert_method: :auto.
• Keep temporary append/returning internals private; do not add a public append_insert_all helper.
• Keep the LIST lambda AST translator hidden. LIST lambda macros are public; the translator is an implementation detail.
• Render DuckDB's Python-style lambda syntax (lambda x : ...) instead of deprecated arrow syntax.
• Keep LIST/MAP/STRUCT natural names in focused modules, but use explicit aliases such as contains_list/2, intersect_list/2, contains_map/2, map_extract_value/2, contains_struct/2, and struct_extract/2 for broad use QuackDB.Ecto imports where names would conflict.
• Keep broad contains/2 dispatch limited to obvious text/spatial cases until LIST/MAP/STRUCT expression typing is reliable enough to dispatch without surprises.
• Keep PIVOT, UNPIVOT, and GROUPING helpers as QuackDB.SQL builders rather than Ecto query DSL extensions.

Ecto analytical helpers

QuackDB.Ecto.Analytics added or expanded helpers for analytical DuckDB expressions:

• Data profiling: summarize/2,3,4 and summarize!/2,3,4.
• Query profiling: QuackDB.Profile.analyze/4, analyze!/4, explain/4, explain!/4, flatten/1, slowest/2, report/2, and decoded profile/operator structs.
• Conditional expressions: QuackDB.Ecto.Conditionals.case_when/1.
• Date/time: atom-aware date_part/2, date_trunc/2, time_bucket/2,3 origins and offsets.
• JSON: json_extract/2, json_extract_string/2, json_exists/2, json_contains/2, plus Ecto access lowering.
• Aggregates: list/1,2, string_agg/2,3, arg_max/2,3, arg_min/2,3.
• Statistical/analytical helpers: median/1, quantile_cont/2, quantile_disc/2, corr/2, stddev/1, variance/1, stddev_pop/1, var_pop/1, var_samp/1, covar_pop/2, covar_samp/2, regr_slope/2, regr_intercept/2, regr_count/2, regr_r2/2, regr_sxx/2, regr_sxy/2, regr_syy/2, skewness/1, kurtosis/1, kurtosis_pop/1, sem/1, entropy/1, mad/1.
• Numeric precision/weighted helpers: favg/1, fsum/1, product/1, weighted_avg/2, geometric_mean/1.
• Approximate helpers: approx_count_distinct/1, approx_quantile/2, approx_top_k/2, reservoir_quantile/2,3.
• Boolean/bit helpers: bool_and/1, bool_or/1, band/1, bor/1, bxor/1, bitstring_agg/1,3.
• Histograms: histogram/1, histogram_exact/2, equi_width_bins/3,4.

Accepted naming decisions before 0.4.0:

• Keep band/1, bor/1, and bxor/1 for aggregate bitwise operations to match Elixir Bitwise naming rather than raw DuckDB bit_and, bit_or, and bit_xor.
• Keep list/1,2 as the DuckDB-native aggregate name. Do not reintroduce duckdb_list/1.
• Keep conditional aggregates expressed through Ecto filter/2; do not add count_if/countif helpers.

Ecto text, regex, spatial, and predicates

• QuackDB.Ecto.Regex exposes DuckDB regexp_* helpers and accepts compatible literal ~r patterns.
• QuackDB.Ecto.Text exposes common string predicates and splitting helpers: contains/2, contains_text/2, starts_with/2, ends_with/2, prefix/2, suffix/2, split_part/3, string_split/2, and string_split_regex/2,3.
• QuackDB.Ecto.Spatial.st_contains/2 is an explicit spatial escape hatch for shared contains/2 use.
• The hidden predicates module is imported by use QuackDB.Ecto only to dispatch shared contains/2.

Accepted naming decisions before 0.4.0:

• Keep contains_text/2 as the explicit text escape hatch for ambiguous shared contains/2 calls.
• Keep st_contains/2 as the explicit spatial escape hatch alongside direct spatial imports.
• Keep ambiguous shared contains/2 calls raising instead of defaulting to spatial.
• Keep the predicates module hidden; contains/2 dispatch is an implementation detail of use QuackDB.Ecto.

Window frames

QuackDB.Ecto.WindowFrames provides rows_between/2, range_between/2, and groups_between/2. They expand to fragment(...) and are intended for Ecto releases that include macro-expanded window frame support. Until QuackDB depends on such a release, examples should continue to show literal frame fragments.

Accepted naming decisions before 0.4.0:

• Keep the module name QuackDB.Ecto.WindowFrames.
• Keep tuple bounds such as {:preceding, 6} and {:following, 1} plus atoms :current_row, :unbounded_preceding, and :unbounded_following. This keeps bounds compile-time data and avoids extra helper macros for each bound.

Direct SQL, sources, and append APIs

• QuackDB.Analytics.summarize/1 renders direct DuckDB SUMMARIZE SQL for table names and raw query tuples.
• Source helpers added QuackDB.Source.sample/2 and QuackDB.Source.histogram_values/3.
• Append helpers added QuackDB.insert_stream/4, insert_stream!/4, insert_table/4, and insert_table!/4.
• Explicit {:map, key_type, value_type} append columns accept ordinary Elixir maps. Plain Elixir maps without an explicit MAP column spec continue to infer as DuckDB STRUCT values.

Maintainer tooling

• The quackdb.functions.snapshot Mix task writes a checked-in DuckDB function catalog snapshot under priv/duckdb_functions/current.exs.
• The snapshot stores normalized QuackDB type specs for overload auditing, but package compilation must not depend on a live DuckDB server.

Pre-release checks

Before tagging 0.4.0:

1. Re-read this file and decide whether open naming review items should change.
2. Run mix ci.
3. Run the full gated integration suite against DuckDB Quack.
4. Run mix docs.
5. Run mix hex.build --unpack and inspect package contents.