Module com.darkcollective.relix.embed

Package com.darkcollective.relix.embed

Class Input

java.lang.Object

com.darkcollective.relix.embed.Input

public final class Input
extends Object

Rows arriving as text — a file, a pipe, a socket, standard input — for Relix.input(String, Input) to name as a relation.

Two kinds, which differ in what a second read of the relation does:

• Re-readable, of(InputFormat, Supplier): the supplier is called for each scan, as Relix.source(java.lang.String, com.darkcollective.relix.symbol.Schema, java.util.function.Supplier<java.util.stream.Stream<com.darkcollective.relix.processor.Row>>) calls its own, so a query that reads the relation twice opens it twice. For a file.
• Single-pass, of(InputFormat, InputStream): the stream is read once. Its rows are kept as they are read, so a later scan — a second query, or a query reading the relation twice — replays them; reading a large stream more than once therefore holds it in memory. For standard input or a pipe.

With no declared heading the heading is inferred from the first records: a delimited format's names come from its header row, and JSON's from the keys the sample uses. A record after the sample whose value does not fit the inferred type is an error naming it; declare the heading, or sample more.

An input is immutable; each method returns a new one.

Since:

1.0

Field Summary

Fields

Modifier and Type	Field	Description
static final int	DEFAULT_SAMPLE	How many records a heading is inferred from unless sample(int) says otherwise.

Method Summary

Modifier and Type	Method	Description
InputFormat	format()	Returns how the text is written.
boolean	isReReadable()	Returns whether each scan opens the text afresh, rather than reading one stream once.
boolean	isUnbounded()	Returns whether the input never ends.
List<String>	names()	Returns the column names a headerless input was given, or empty when its first line is its header row.
Input	names(String first, String... more)	This input, read as text with no header row whose columns are columns, in order — their types inferred as for any heading, unless one is declared.
static Input	of(InputFormat format, InputStream stream)	A single-pass input: stream is read once, and closed by the session when it is finished with.
static Input	of(InputFormat format, Supplier<InputStream> open)	A re-readable input: open is called for each scan, and the engine closes what it returns.
int	sample()	Returns how many records a heading is inferred from.
Input	sample(int records)	This input, its heading inferred from the first records records.
Optional<Schema>	schema()	Returns the declared heading, if one was.
Input	schema(Schema heading)	This input, read as heading rather than an inferred one.
Input	unbounded()	This input, marked as never ending: a log followed as it is written, a feed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

DEFAULT_SAMPLE

public static final int DEFAULT_SAMPLE

How many records a heading is inferred from unless sample(int) says otherwise.

See Also:

• Constant Field Values

Method Details

of

public static Input of(InputFormat format,
 Supplier<InputStream> open)

A re-readable input: open is called for each scan, and the engine closes what it returns.

Parameters:

format - how the text is written; must not be null

open - opens the text afresh; must not be null

Returns:

the input

Since:

1.0

of

public static Input of(InputFormat format,
 InputStream stream)

A single-pass input: stream is read once, and closed by the session when it is finished with.

Parameters:

format - how the text is written; must not be null

stream - the text; must not be null

Returns:

the input

Since:

1.0

schema

public Input schema(Schema heading)

This input, read as heading rather than an inferred one. A delimited format matches its header to the heading's names; JSON reads each name's key.

Parameters:

heading - the heading; must not be null

Returns:

the input

Since:

1.0

names

public Input names(String first,
 String... more)

This input, read as text with no header row whose columns are columns, in order — their types inferred as for any heading, unless one is declared.

Without names, a delimited input's first line is its header row, and one that has none cannot be read with an inferred heading: nothing else would name its columns.

Parameters:

first - the first column's name

more - the rest, in order; each column is named once

Returns:

the input

Throws:

IllegalArgumentException - for a JSON format, whose columns are its keys, or for a name given twice

Since:

1.0

names

public List<String> names()

Returns the column names a headerless input was given, or empty when its first line is its header row.

Returns:

the column names a headerless input was given, or empty when its first line is its header row

Since:

1.0

sample

public Input sample(int records)

This input, its heading inferred from the first records records.

Parameters:

records - how many; at least 1

Returns:

the input

Since:

1.0

unbounded

public Input unbounded()

This input, marked as never ending: a log followed as it is written, a feed.

The engine then treats the relation as it treats any endless one: a query streams it, a row at a time, and one that would have to read all of it first — a sort, a grouping, a collecting terminal — is refused before it starts. A single-pass input marked so keeps nothing, and can be read by one scan only. A JSON array is one document and cannot be; read the stream as InputFormat.NDJSON.

Returns:

the input

Throws:

IllegalArgumentException - for a JSON array

Since:

1.0

format

public InputFormat format()

Returns how the text is written.

Returns:

how the text is written

Since:

1.0

schema

public Optional<Schema> schema()

Returns the declared heading, if one was.

Returns:

the declared heading, if one was

Since:

1.0

sample

public int sample()

Returns how many records a heading is inferred from.

Returns:

how many records a heading is inferred from

Since:

1.0

isUnbounded

public boolean isUnbounded()

Returns whether the input never ends.

Returns:

whether the input never ends

Since:

1.0

isReReadable

public boolean isReReadable()

Returns whether each scan opens the text afresh, rather than reading one stream once.

Returns:

whether each scan opens the text afresh, rather than reading one stream once

Since:

1.0