Contents
SQL reference
Generated by scripts/gen-reference.sh from sql/pg_sift--4.3.sql; do not edit by hand. Descriptions are the COMMENT ON of that script (\df+),
or docs/reference-notes.tsv for the objects of the released scripts. scripts/gen-reference.sh --check fails when this file is stale or an object has no description.
Schema sift: 70 functions, 6 views, 2 tables, 2 operator classes, 1 operator. The first column is the signature with the defaults; Since is the first release that has the name; the section is the one of USAGE.md that uses it most.
Settings (sift.*) are in the table of Maintenance and operations; the fixed limits are in LIMITS.md.
Search and ranking
The sift index (BM25): the operator, ranking, query helpers, facets and the inspection of the index.
| Object | Kind | Returns | Since | Description |
|---|---|---|---|---|
text @@> text |
operator | bool |
1.0 | Full-text match of a text against a SiftQL query (words, phrases, prefixes, fuzzy terms, NOT, fields); a sift index answers it, with BM25 ranking through sift.score. See Ranking, filters and joins. |
sift.facet_counts(tbl regclass, key text, query text, facets jsonb, filter text DEFAULT NULL, hits bool DEFAULT false) |
function | setof (facet text, kind text, value text, lo text, hi text, count int8) |
3.1 | Facet counts over a search: terms, range, histogram and date_histogram facets of any column type, several in one call. See Facets. |
sift.facet_sql(tbl regclass, key text, query text, facets jsonb, filter text DEFAULT NULL, hits bool DEFAULT false) |
function | text |
3.1 | The SQL statement that facet_counts runs, one scan per facet. See Facets. |
sift.facets(index regclass, facet_index regclass, query text, lim int DEFAULT 10, nulls bool DEFAULT false) |
function | setof (value text, count int8) |
1.1 | Counts of the matches of a query per value of a keyword sift index, most frequent first. See Facets. |
sift.field_query(query text, fields text, index regclass DEFAULT NULL) |
function | text |
3.1 | The query with the weights of its fields: each term searched in every field with its boost times the field weight. See Analyzers, phrases, several columns. |
sift.highlight(doc text, query text, start_tag text DEFAULT '<b>', stop_tag text DEFAULT '</b>', index regclass DEFAULT NULL) |
function | text |
1.0 | The text with the matched terms of a query wrapped in start_tag and stop_tag. |
sift.index_info(index regclass) |
function | (relation_blocks int8, high_water int8, free_blocks int8, reusable_blocks int8, free_extents int8, segments int4, max_segments int4, ndocs int8, sum_dl int8, maintenance_busy bool) |
1.2 | Space and directory state of a sift index: blocks, free list, segments, documents and whether maintenance runs. See Maintenance and operations. |
sift.json_build_object(VARIADIC "any") |
function | json |
3.5 | json_build_object with the type lookups of each argument made once per call site: the same text as the core function, for one or more arguments |
sift.match(doc text, query text) |
function | bool |
1.0 | The function behind @@> with the default analyzer; the planner rebinds it to the index analyzer. |
sift.match_idx(doc text, query text, index oid) |
function | bool |
1.0 | The function behind @@> for a column whose sift index uses another analyzer. See Analyzers, phrases, several columns. |
sift.max_score(tid) |
function | real |
1.0 | The largest BM25 score the query can give, for a scan (error anywhere else). See Ranking, filters and joins. |
sift.parse_query(query text, index regclass DEFAULT NULL) |
function | text |
1.0 | The parsed form of a SiftQL query under an index analyzer, as text. See Analyzers, phrases, several columns. |
sift.score(tid) |
function | real |
1.0 | BM25 score of the row of a sift scan, in the same query (error anywhere else). See Ranking, filters and joins. |
sift.sections(VARIADIC parts text[]) |
function | text |
3.1 | Joins the fields of a document into the text a fields index is built on. See Analyzers, phrases, several columns. |
sift.segment_postings(index regclass) |
function | setof (gen int8, df_class text, terms int8, postings int8, inline_terms int8, list_terms int8, grouped_terms int8, codec_bytes int8, sidecar_bytes int8, bits_per_posting float8) |
1.0 | Postings of a sift index by segment and document-frequency class: representation counts, codec bytes and bits per posting. |
sift.segments(index regclass) |
function | setof (gen int8, kind text, ndocs int8, sum_dl int8, avgdl float8, bytes int8, sb_lo int4, sb_hi int4, dirty bool, nterms int8, avgdl_ref float8, docmap_bytes int8, postings_bytes int8, dict_bytes int8, live_bytes int8, extents int4, dead_docs int8) |
1.0 | One row per segment of a sift index: documents, terms, bytes by section, dirty and dead documents. See Maintenance and operations. |
sift.tokenize(doc text, index regclass DEFAULT NULL, stemmer text DEFAULT NULL, case_folding bool DEFAULT NULL, accent_folding bool DEFAULT NULL) |
function | setof (token text, pos int4, start_offset int4, end_offset int4) |
1.0 | The tokens of a text under an index analyzer or given options: token, position and character offsets. See Analyzers, phrases, several columns. |
sift.verify(index regclass, heapallindexed bool DEFAULT false) |
function | void |
1.0 | Checks the structure of a sift or sift_col index (and with heapallindexed, that every visible row is in it); raises on a problem. col_verify is the same call. See Analyzers, phrases, several columns. |
sift.text_ops FOR TYPE text USING sift (default) |
operator class | 1.0 | Default operator class of the sift index for text: the @@> operator. |
Column index
The sift_col index: what it stores, and the operator classes that let the planner scan it.
| Object | Kind | Returns | Since | Description |
|---|---|---|---|---|
sift.approx_count_distinct(anyelement) |
function | int8 |
3.4 | An estimate of the distinct values of x (relative standard error 0.81%), the same in every plan; count(DISTINCT x) stays exact. See Column indexes, aggregates and sift_table. |
sift.cluster_advice(rel regclass DEFAULT NULL, min_rows int8 DEFAULT 100000, key text DEFAULT NULL) |
function | setof (tbl regclass, index regclass, order_by text, units int8, units_now float8, units_after float8, saved_rows int8, churn_pct float8, verdict text, reason text, command text) |
3.3 | Which physical order of a table (CLUSTER, pg_repack –order-by) would let the scans of its sift_col index skip the most units, one row per index: units read now and after, rows saved, churn, a verdict with its reason, and the pg_repack call with the VACUUM (ANALYZE) that follows; key asks about your own list of leaves. See Maintenance and operations. |
sift.col_arena_status() |
function | (slots_in_use int4, slots int4, bytes_in_use int8, rows_stored int8, put_fallbacks int8, seals_forced int8, rows_rebuilt int8, segments int4, bytes_taken int8) |
4.3 | The shared arena of the write buffers kept as references (sift.col_wbuf_ref): slots in use, bytes and rows held, rows written with their values for want of room, buffers sealed to give a slot back, rows built again from the heap since the server started, the 1 MB segments of shared memory made so far (they stay until the server stops) and the bytes of them that buffers hold See Maintenance and operations. |
sift.col_clustering(index regclass, width_pct float8 DEFAULT 1) |
function | setof (leaf int4, path text, units int8, zoned_units int8, useful_pct float8, point_units float8, range_units float8, range_ideal float8, correlation float8, verdict text, depth_max int8) |
3.3 | How well the rows of a sift_col index are ordered for its zone maps, one row per leaf: the units an equality or a range touches, the most units any value touches (depth_max), the correlation and a verdict (clustered, partial or scattered). See Column indexes, aggregates and sift_table. |
sift.col_connection_fill(child regclass) |
function | setof (ordinal int4, segments int8, filled int8) |
4.3 | For each connection of a sift_col index: its segments, and those that hold the found flags under a stamp |
sift.col_connection_list(child regclass) |
function | setof (ordinal int4, fk text, declaration text, parent_index regclass, automatic boolean) |
4.3 | The connections a sift_col index declares with its option connect: their place in the option, the column that holds the parent key, the text, the parent index that serves each (NULL when the names do not resolve now) and whether CREATE INDEX or REINDEX chose the connection from the foreign keys |
sift.col_connection_state(parent regclass) |
function | (lineage int8, records int8, stamp text) |
4.3 | The key journal of a sift_col index that a child index is connected to: its lineage, the records appended so far, and what a stamp taken now says (ok, or why a derived value could not be vouched) |
sift.col_connections |
view | 4.3 | The connections of the sift_col indexes with the option connect: the child index, the parent index that serves each, the text, the state of the key journal of the parent, and whether the found flags of its segments are filled (fill) | |
sift.col_extents(index regclass) |
function | setof (what text, gen int8, first_block int8, nblocks int8, pending bool) |
4.0 | Every run of blocks of the file of a sift_col index: segment extents, headers and liveness runs, write buffers, the free list and the free extents (pending: a snapshot may still read it). See Maintenance and operations. |
sift.col_index_info(index regclass) |
function | (relation_blocks int8, high_water int8, free_blocks int8, reusable_blocks int8, free_extents int8, segments int4, max_segments int4, rows int8, bytes int8, units int8, buffers int4, leaves int4, maintenance_busy bool, simd text, preagg_bytes int8, preagg_units int8) |
3.0 | Space and directory state of a sift_col index: blocks, free list, segments, rows, units (the superblocks the segments cover once; the units a key-cut segment stores, each) and the kernel level of the scans. See Column indexes, aggregates and sift_table. |
sift.col_index_status |
view | 3.3 | One row per sift_col index the caller can read, for the DBA of a large table: file, segment, free and reusable bytes, segments against the limit, rows in the segments (dead ones included), units listed against covered, dirty segments and dead rows, rows in write buffers, the maintenance state and the chain of sift.col_maintenance_status (last VACUUM, why a rewrite is due, what blocks it). See Maintenance and operations. | |
sift.col_leaves(index regclass) |
function | setof (leaf int4, path text, kind text, type text, const_chunks int8, for_chunks int8, pack_chunks int8, codec_chunks int8, inline_chunks int8, chunk_bytes int8, dict_bytes int8) |
3.0 | One row per leaf of a sift_col index: its chunks by encoding, their bytes and the bytes of its dictionaries. See Column indexes, aggregates and sift_table. |
sift.col_maintenance_status(index regclass) |
function | (heap regclass, last_vacuum timestamptz, changed_rows int8, vacuum_at int8, rewrite_due text, last_request timestamptz, blocked_by text[]) |
3.3 | Where the VACUUM and the rewrite that keep a sift_col index answerable stand: the table, its last VACUUM, the rows changed since and the number that starts the next, why the rewrite is due, the last request of a worker, and blocked_by: what keeps a worker from running (setting off, autovacuum_enabled false, a standby, a snapshot holding back the last rewrite). See Maintenance and operations. |
sift.col_sections(rel regclass) |
function | setof (section text, leaf text, bytes int8) |
3.0 | Where the bytes of a sift_col index or a sift_table go, one row per kind; they add up to pg_relation_size. |
sift.col_segments(index regclass) |
function | setof (gen int8, kind text, rows int8, bytes int8, sb_lo int4, sb_hi int4, units int4, dirty bool, dead_rows int8, extents int4, format int4, preagg_bytes int8) |
3.0 | One row per segment of a sift_col index: rows, units, bytes, column format and the bytes of its pre-aggregates. See Maintenance and operations. |
sift.col_space(index regclass) |
function | (relation_blocks int8, high_water int8, used_blocks int8, reusable_blocks int8, pending_blocks int8, free_extents int4, largest_free_extent int8, tail_what text, tail_gen int8, tail_end int8, shrink_to int8, shrink_blocks int8) |
4.0 | The free space of a sift_col file in one row: used, reusable and pending blocks, free extents, the owner of the last used block, and where the VACUUM shrink would end the file. See Maintenance and operations. |
sift.col_stamps(index regclass) |
function | setof (gen bigint, entries bigint, stamp xid) |
4.0 | The immutable segments of a sift_col index with track_changes and the xid before which every transaction that inserted an entry of the segment committed; NULL when the segment does not say |
sift.col_track_convert() |
function | integer |
4.2.1 | Makes each sift_col index the dependent of its two track_changes triggers (what 4.2.1 does for the indexes of an older release), so that DROP INDEX CONCURRENTLY can drop it; returns the number of triggers converted See Column indexes, aggregates and sift_table. |
sift.col_track_old_rows() |
function | trigger |
4.0 | The statement trigger of the sift_col option track_changes: it writes a tombstone for the entries of the rows a statement deleted or gave another key; created and dropped with the index, never by hand. |
sift.col_tracking(index regclass) |
function | (track_changes bool, triggers bool, complete bool, heap_free bool) |
4.0 | What the tombstone log of a sift_col index with track_changes can be taken for: track_changes is on, the two statement triggers are the ones that made the log complete, the log was made complete, and all of it holds now See Column indexes, aggregates and sift_table. |
sift.col_verify(index regclass, heapallindexed bool DEFAULT false) |
function | void |
3.0 | Checks the structure of a sift_col index (and with heapallindexed, its rows against the heap); raises on a problem. |
sift.index_advice(index regclass) |
function | setof (leaf text, kind text, held text, sampled int4, share int4, advice text) |
3.3 | The profile of the columns of a sift_col index and what its options could still use: per column its kind (dimension, key, unique, date, measure, text, list), what the index holds of it and, over 32 evenly spaced units, the share that satisfy the rule of a dimension (at most 256 distinct values) or, per pair of dimensions, of a rollup of the rows; advice only, nothing is changed. See Column indexes, aggregates and sift_table. |
sift.index_choices(index regclass) |
function | setof (choice text, kind text, value text, cost text, typical_cost text, why text, off text, slug text, doc text) |
4.0.3 | What CREATE INDEX or REINDEX of a sift_col index chose or advises: choice, kind, value, cost measured on the index, typical cost, the reason and the command that turns it off See Column indexes, aggregates and sift_table. |
sift.key_cut_decision(index regclass) |
function | (leaf text, units float8, sampled float8, reads float8, ideal float8, growth_pct float8, decision text, reason text) |
3.4 | What CREATE INDEX or REINDEX of a sift_col index would decide for key_cut now, from a sample of the heap: the key-shaped column, the units an equality on it reads (reads) against the units its rows fill (ideal), the predicted growth of the index when cut by it, the decision (cut, advise or none) and the reason. Changes nothing. |
sift.suggest_paths(rel regclass, column_name text, sample int4 DEFAULT 2000) |
function | text |
3.3 | The paths option that a jsonb column asks for, read from a sample of its documents (evenly spaced blocks, the same answer for the same table): typed paths for the scalar keys, a wildcard for a map of more than 4 keys of one type, a group for an array of objects, free text (values of more than 64 bytes on average) left out; advice only, NULL when no key qualifies. See Column indexes, aggregates and sift_table. |
sift.col_*_ops |
operator class | 3.3 | Operator classes per type (int2, int4, int8, float4, float8, date, timestamp, timestamptz, bool, numeric, text, bpchar, uuid) that let the planner scan a sift_col index; opt-in per column. | |
sift.col_ops FOR TYPE anyelement USING sift_col (default) |
operator class | 3.0 | Default operator class of the sift_col index: it has no operators, the index is read by the column scans. |
Tables
The sift_table access method.
| Object | Kind | Returns | Since | Description |
|---|---|---|---|---|
sift.table_find_stale_versions(tbl regclass, sample integer DEFAULT 10) |
function | setof (duplicate_keys bigint, sample_keys text[]) |
4.2.2 | The number of primary key values of the table that are on more than one row (the old versions of updated rows that a VACUUM of 4.0.0 to 4.2.1 made live again) and up to sample of them; a row that was deleted and came back has no copy and is not found |
sift.table_get_option(tbl regclass, name text) |
function | text |
4.2 | The value of a per-table option in force on a sift_table: its own option, else the setting. See Maintenance and operations. |
sift.table_option_values |
table | 4.2 | The per-table options of the sift_tables, one row for each option a table sets (sift.table_set_option writes it, sift.table_options reads it); dumped with the database. | |
sift.table_option_values_trg() |
function | trigger |
4.2 | Trigger of sift.table_option_values: skips the row of a table the database does not have and replaces the entry of the table in the cache of every backend. |
sift.table_options(tbl regclass DEFAULT NULL) |
function | setof (rel regclass, name text, value text, source text, default_value text) |
4.2 | The per-table options of the sift_tables the caller may see (or of one): value in force, source (table, setting, default) and built-in default. See Maintenance and operations. |
sift.table_paths |
table | 3.2 | The declared JSON paths of the jsonb columns of sift_table tables (one row per table and column), dumped with the extension. | |
sift.table_paths_maintained |
view | 3.3 | The declared JSON paths of the sift_tables the caller owns or may maintain (relid, attname, spec); sift.table_paths lists every table and is for superusers. | |
sift.table_reset_option(tbl regclass, name text DEFAULT NULL) |
function | void |
4.2 | Takes an option (all of them when the name is NULL) off a sift_table, so that the setting applies again. See Maintenance and operations. |
sift.table_segments(tbl regclass) |
function | setof (gen int8, kind text, rows int8, bytes int8, sb_lo int4, sb_hi int4, units int4, dead_rows int8, format int4, unfrozen bool, min_xid xid, max_xid xid) |
3.0 | One row per segment of a sift_table: write buffers, sealed buffers, column segments (rows, units, dead rows, format, unfrozen) and tombstones. See Column indexes, aggregates and sift_table. |
sift.table_set_option(tbl regclass, name text, value text) |
function | void |
4.2 | Sets a per-table option of a sift_table (the name of a sift.table_* setting without the prefix); the value is checked as the setting checks it. The table option beats the setting whatever its source. See Maintenance and operations. |
sift.table_set_paths(tbl regclass, col name, spec text) |
function | void |
3.2 | Declares the JSON paths of a jsonb column of a sift_table, in the grammar of the paths option of sift_col; an empty spec removes it. |
sift.table_space(tbl regclass) |
function | (relation_blocks int8, high_water int8, free_blocks int8, reusable_blocks int8, free_extents int8, vblocks_left int8) |
3.0 | Space of a sift_table: file blocks, free list, reusable blocks and the virtual TID blocks left. See Column indexes, aggregates and sift_table. |
Maintenance and workers
Promotion, merging, rewriting and the background workers, of all three.
| Object | Kind | Returns | Since | Description |
|---|---|---|---|---|
sift.col_maintain(index regclass) |
function | bool |
3.2 | The rewrite of sift.col_auto_merge now, in this session: seals the write buffer and merges every segment when churn has scattered the index; false when nothing is due. See Maintenance and operations. |
sift.col_maintenance_due(index regclass, automatic bool DEFAULT true) |
function | text |
3.2 | Why col_maintain would rewrite the index now (dirty units, fragmented units, write buffer rows), NULL when it is not due. See Maintenance and operations. |
sift.col_merge(index regclass, force bool DEFAULT false) |
function | int4 |
3.0 | Merges the segments of a sift_col index into fewer; force merges even when no policy asks; returns the segments merged. See Maintenance and operations. |
sift.col_promote(index regclass) |
function | int4 |
3.0 | Turns the write buffer of a sift_col index into column segments; returns the segments written. See Maintenance and operations. |
sift.col_refresh(index regclass, max_segments int4 DEFAULT NULL) |
function | (refreshed int4, remaining int4) |
3.3 | Rewrites the segments of a sift_col index whose pre-aggregates differ from its current options, at most max_segments per call; returns the segments rewritten and those left. |
sift.col_rollup_counters() |
function | (requested int8, refreshed int8, skipped int8, dropped int8, queued int4, refreshing int4) |
3.1 | Server counters of the on-demand refresh of unit rollups: requested, refreshed, skipped, dropped, queued, refreshing. |
sift.col_rollup_queue() |
function | setof (index regclass, segment int8, units int4, requested_at timestamptz, state text) |
3.1 | The queued requests to refresh the rollups of a segment, with their state. |
sift.col_rollup_refresh(index regclass) |
function | int4 |
3.1 | Refreshes the queued rollup requests of a sift_col index now, in this session; returns the segments rewritten. See Maintenance and operations. |
sift.col_rollup_requests |
view | 3.1 | The rows of col_rollup_queue as a view. | |
sift.col_rollup_state |
view | 3.1 | The columns of col_rollup_counters as a view. | |
sift.merge(index regclass, force bool DEFAULT false) |
function | int4 |
1.0 | Merges the segments of a sift or sift_col index into fewer; force merges even when no policy asks; returns the segments merged (col_merge is the same call). See Maintenance and operations. |
sift.promote(index regclass) |
function | int4 |
1.0 | Turns the write buffer of a sift index into an immutable segment, or that of a sift_col index into column segments; returns the buffers promoted (col_promote is the same call). See Maintenance and operations. |
sift.table_maintain(tbl regclass) |
function | (busy bool, dead_rows int8, promoted int4, merged int4, blocks_before int8, blocks_after int8) |
3.2 | VACUUM’s work on the column segments and the file of a sift_table without its indexes: clears dead rows, promotes buffers, rewrites mostly dead segments, returns the free end of the file. See Maintenance and operations. |
sift.worker_state(index regclass) |
function | (segments int4, sealed int4, running bool, failures int4, failed_at timestamptz, next_retry timestamptz, error_code text, last_error text) |
3.3 | Maintenance state of one sift or sift_col index: directory entries, sealed write buffers, whether maintenance runs and, when the last background step failed, the failures in a row, when, the earliest retry, the SQLSTATE and the message. Read through sift.workers. |
sift.workers |
view | 3.3 | One row per sift and sift_col index and per sift_table whose table you can read (index: the index, or the table): segments, sealed write buffers, whether maintenance runs, the failures in a row of the background, when, the next retry, the SQLSTATE and the last error (a sift_table keeps none), and why a sift_col index would be rewritten (due). See Maintenance and operations. |
Diagnostics and upgrade
Session statistics, why a query kept the normal plan, what an upgrade leaves to do.
| Object | Kind | Returns | Since | Description |
|---|---|---|---|---|
sift.col_rollup_misses() |
function | setof (rel regclass, reason text, fixable bool, scans int8, units int8) |
3.3 | The scans of this session that could not answer from the pre-aggregates of their sift_col index, by index and reason, and whether other index options would answer them. See Column indexes, aggregates and sift_table. |
sift.explain_why(query text) |
function | setof (arm text, used bool, slug text, reason text, scan_cost float8, normal_cost float8) |
3.3 | Why each candidate path of the aggregate pushdown kept or left the normal plan for one SELECT, planned and not run: one row per arm with the first reason it gave up; a statement with no aggregate gets the row index: whether the plan reads a sift_col index and, if not, no_source, where or cost. See Column indexes, aggregates and sift_table. |
sift.help(slug text DEFAULT NULL) |
function | setof (id text, kind text, level text, message text, detail text, hint text, decision text, why text, off text, doc text) |
4.0.3 | The row of docs/messages.tsv of a pg_sift message or choice by its slug, or the registry row of a refusal slug of sift.explain_why (all message rows without an argument) See Column indexes, aggregates and sift_table. |
sift.refusal_actions() |
function | setof (slug text, action text) |
4.2 | What to change for each slug of sift.refusal_slugs(): the statement, the index or a setting (the hint of the notice of sift.explain_refusals); join it to sift.explain_why on slug |
sift.refusal_slugs() |
function | setof (slug text, class text, reason text) |
3.3 | The slugs that sift.explain_why and sift.stats() name, with their class (limit: the query has more of something than a fixed limit of the extension allows; semantic: otherwise) and the reason. See Column indexes, aggregates and sift_table. |
sift.stats() |
function | setof (name text, value int8) |
3.3 | What the aggregate pushdown (Custom Scan (SiftAgg)) scans of this session did: one row per counter and per refusal slug. See Column indexes, aggregates and sift_table. |
sift.stats_reset() |
function | void |
3.3 | Resets the session counters that sift.stats() reports. See Column indexes, aggregates and sift_table. |
sift.upgrade_commands() |
function | setof (kind text, object regclass, reason text, command text, required bool) |
3.3 | What an update leaves to do for the indexes and tables the caller owns or may maintain, one row per command, the cheapest first: kind (reindex, rewrite), the index or table, the reason and the statement; required when queries miss rows until it runs. Changes nothing. See Column indexes, aggregates and sift_table. |
sift.version() |
function | text |
1.2 | Version of the loaded library (the installed extension version is in pg_extension). See Maintenance and operations. |
Internal
Not meant to be called: sift._table_option_names, sift._table_option_stored, sift.approx_count_distinct_combine, sift.approx_count_distinct_deserial, sift.approx_count_distinct_final, sift.approx_count_distinct_serial, sift.approx_count_distinct_trans, sift.col_handler, sift.col_ops_unused, sift.col_unit_agg, sift.col_unit_hist, sift.facet_cap, sift.facet_part, sift.match_support, sift.matchsel, sift.publication_check, sift.sift_handler, sift.table_ddl_check, sift.table_handler, sift.table_option_values_drop, sift.table_paths_check, sift.table_paths_drop, sift.tblref_in, sift.tblref_out. Names starting with _ are for the tests.