Struct Given 

pub struct Given {
    pub delimiter: Option<u8>,
    pub quote: Option<u8>,
    pub escape: Option<u8>,
    pub header: Option<bool>,
    pub nulls: Option<Vec<String>>,
    pub names: Option<Vec<String>>,
    pub typed: bool,
}

What the caller said about how the file is written, where the sniffer would otherwise decide.

Every field is optional and a None means nothing was said, which is the common case and is the one the sniffer is for. What is given is not sniffed: read_csv('f.csv', delim=';') does not try the four candidates and pick one, it uses the semicolon, and a file that is really comma separated then comes back as one column. That is DuckDB’s behaviour and it is the useful one, since somebody who wrote the delimiter down knows something the first megabyte of the file does not say.

A given value also changes the block DuckDB prints under a conversion error, where a line reads (Set By User) rather than (Auto-Detected), which is why this is carried into the reader rather than folded into a Dialect and forgotten.

The last three are not punctuation, and they are here because they travel the same road: the binder works them out from the call to sniff the file with and the executor works them out again from the plan to read it with, and a second struct beside this one would be a second thing for the two ends to keep in step.

Fields

delimiter: Option<u8>

The byte between two fields.

quote: Option<u8>

The byte that opens and closes a field.

escape: Option<u8>

The byte that makes the next quote a literal one.

header: Option<bool>

Whether the first line names the columns.

nulls: Option<Vec<String>>

The strings that read as a null, which is nullstr on a call and NULL on a COPY.

None is DuckDB’s default, where an empty field is a null. A field is compared once its quotes and escapes are gone, so "NA" is as much a null as NA is, and with any list here an empty field is an empty string rather than a null. Both were measured on v2.0.0-dev84237, where allow_quoted_nulls is on unless it is turned off, and it cannot be turned off here.

names: Option<Vec<String>>

What to call the columns, first column first, in place of what the header or the generator called them. A list shorter than the file names the columns it reaches.

typed: bool

Whether the column types are the caller’s rather than the sniffer’s, which is what COPY t FROM does with the table’s.

The reader converts to whatever types it is told either way. What this changes is the error for a value that does not convert, which tells somebody who set the type to look at the data and somebody who did not to set one.

Implementations

impl Given

pub fn shown(given: Option<u8>, sniffed: Option<u8>) -> String

How a byte is written in the block under a conversion error, and where it came from.

pub fn null_strings(&self) -> Option<Vec<Vec<u8>>>

The strings that read as a null, with DuckDB’s default of the empty string written out as None so that a caller who wrote NULL '' gets the same fast test as one who wrote nothing.

pub const fn source(given: bool) -> &'static str

What the block calls a value the caller gave and one it worked out.

Trait Implementations

impl Clone for Given

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Given

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Given

fn default() -> Self

Returns the “default value” for a type.

impl Eq for Given

impl PartialEq for Given

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Given