Documentation
¶
Overview ¶
Package exporttrunc is what every export tool does when a bound cut the result it was writing (#2057): trino_export at a row limit, api_export and graphql_export at a page walk's page bound. The tools share one judgment so they cannot disagree about when a cut file is refused, what the response says, and how the asset it lands in is marked.
A cut the caller asked for (its own limit or max_pages) writes the file and flags it. A cut the caller did not ask for (the deployment's cap, or a walk's built-in default bound) refuses and writes nothing, unless the caller passes on_truncation "warn". Either default is overridden by on_truncation.
Index ¶
Constants ¶
const ( // SourceRequest is a bound the caller set: trino_export's limit, a page // walk's max_pages. SourceRequest = "request" // SourceDeployment is a bound the caller did not set: the deployment's // row cap, or a page walk's built-in default page bound. SourceDeployment = "deployment" )
Where the bound that cut a result came from.
const ( UnitRows = "rows" UnitPages = "pages" )
What a bound counts.
const ( // PolicyFail refuses a cut result and writes nothing. PolicyFail = "fail" // PolicyWarn writes a cut result and flags it. PolicyWarn = "warn" )
on_truncation values.
const ( MetaTruncated = "truncated" MetaLimitApplied = "limit_applied" MetaLimitSource = "limit_source" MetaLimitUnit = "limit_unit" )
The metadata keys a truncated version and its asset carry. The portal version store strips them from an asset whose new version carries no metadata, so they only ever describe the content the asset holds now.
const Tag = "_sys-truncated"
Tag is the reserved tag an asset carries while its current version is a truncated export. The portal version store adds and removes it with the version, so a complete version written later, by any path, clears it.
const WalkSchemaProperties = `` /* 1114-byte string literal not displayed */
WalkSchemaProperties is the on_truncation, expect_rows and expect_min_rows properties of an export whose bound is a page walk's (api_export, graphql_export), as JSON Schema property entries to splice into the tool's properties object, so the two describe one judgment in one set of words.
Variables ¶
var ErrExpectNeedsWalk = errors.New("expect_rows and expect_min_rows count the items a page walk merges; set paginate, or drop them")
ErrExpectNeedsWalk is the refusal for a count expectation on an export that is not a page walk: a single response has no item count to hold it to.
Functions ¶
func Carry ¶
Carry is the truncation keys of an older version's metadata, for a revert that makes that version's content current again, or nil when it records no cut.
func Sentences ¶
Sentences joins a message's sentences, dropping the empty ones, so a part that said nothing leaves no doubled space.
Types ¶
type Judgment ¶
type Judgment struct {
Limit Limit
// Truncated is the source's own signal that the bound cut the result.
Truncated bool
// Written is the count the export would write: rows, or items merged.
Written int
// WrittenUnit names Written in a sentence ("rows", "items").
WrittenUnit string
Options Options
// Unordered marks a result whose order the statement does not fix (a
// query with no top-level ORDER BY). Only a row export knows this; a page
// walk leaves it false.
Unordered bool
}
Judgment is what Judge needs to know about one export.
type Limit ¶
type Limit struct {
// Applied is the bound's value.
Applied int
// Source is SourceRequest or SourceDeployment.
Source string
// Unit is what Applied counts: UnitRows or UnitPages.
Unit string
// Key names what set the bound, for the sentence a cut is reported in:
// the config key of a deployment cap ("portal.export.max_rows") or the
// parameter the caller set ("limit").
Key string
// Remedy is what the caller can do instead, appended to a refusal. Each
// tool has its own.
Remedy string
// Name is what the bound is called in a sentence. Empty takes the
// source's: "the requested limit" or "the deployment cap".
Name string
}
Limit is the bound a result was read under.
type Options ¶
type Options struct {
// OnTruncation is "fail" or "warn"; empty takes the default for the
// bound's source.
OnTruncation string `json:"on_truncation,omitempty"`
// ExpectRows is the exact count the export must write.
ExpectRows *int `json:"expect_rows,omitempty"`
// ExpectMinRows is the fewest the export may write.
ExpectMinRows *int `json:"expect_min_rows,omitempty"`
}
Options is what a caller passes on an export call to decide what a cut or an unexpected count does. Each export tool's input embeds it.
func (Options) Validate ¶
Validate refuses an on_truncation value outside the enum, a negative expectation, and both expectations at once.
func (Options) ValidateWalk ¶
ValidateWalk is Validate for an export whose count is a page walk's (api_export, graphql_export): walk says whether the call walks, and a count expectation on one that does not is refused.
type Outcome ¶
type Outcome struct {
Report Report
// Refusal, when set, is the error the call returns instead of writing.
Refusal string
// Note is what the success message says beyond the count. Empty for a
// complete result nothing else is said about.
Note string
}
Outcome is what an export does with its result.
type Report ¶
type Report struct {
// Truncated reports that the bound cut the result: the source had more
// past it.
Truncated bool `json:"truncated"`
LimitApplied int `json:"limit_applied,omitempty"`
LimitSource string `json:"limit_source,omitempty"`
LimitUnit string `json:"limit_unit,omitempty"`
// ArbitrarySubset reports that a cut result came from a statement with no
// top-level ORDER BY, so which rows it kept is the engine's choice and can
// differ on the next run.
ArbitrarySubset bool `json:"arbitrary_subset,omitempty"`
// ExpectMismatch, under on_truncation "warn", is the expectation the
// written count missed. A miss without "warn" refuses instead.
ExpectMismatch string `json:"expect_mismatch,omitempty"`
}
Report is the fields every export output carries beside its count when a bound applied to it.
func FromMetadata ¶
FromMetadata reads a Report back from a version's or an asset's metadata, for an answer that names an export written earlier (an idempotency hit). It is nil when the metadata records no cut.
Source Files