org.apache.arrow.vector

Interface ValueVector

All Superinterfaces:

AutoCloseable, Closeable, Iterable<ValueVector>

All Known Subinterfaces:

FieldVector, FixedWidthVector, NullableVector, RepeatedValueVector, VariableWidthVector

All Known Implementing Classes:

AbstractContainerVector, AbstractMapVector, BaseDataValueVector, BaseRepeatedValueVector, BaseValueVector, BigIntVector, BitVector, DateVector, DecimalVector, Float4Vector, Float8Vector, IntervalDayVector, IntervalYearVector, IntVector, ListVector, MapVector, NullableBigIntVector, NullableBitVector, NullableDateVector, NullableDecimalVector, NullableFloat4Vector, NullableFloat8Vector, NullableIntervalDayVector, NullableIntervalYearVector, NullableIntVector, NullableMapVector, NullableSmallIntVector, NullableTimeStampVector, NullableTimeVector, NullableTinyIntVector, NullableUInt1Vector, NullableUInt2Vector, NullableUInt4Vector, NullableUInt8Vector, NullableVarBinaryVector, NullableVarCharVector, SmallIntVector, TimeStampVector, TimeVector, TinyIntVector, UInt1Vector, UInt2Vector, UInt4Vector, UInt8Vector, UnionVector, VarBinaryVector, VarCharVector, ZeroVector

public interface ValueVector
extends Closeable, Iterable<ValueVector>

An abstraction that is used to store a sequence of values in an individual column. A value vector stores underlying data in-memory in a columnar fashion that is compact and efficient. The column whose data is stored, is referred by getField(). It is important that vector is allocated before attempting to read or write. There are a few "rules" around vectors:

• values need to be written in order (e.g. index 0, 1, 2, 5)
• null vectors start with all values as null before writing anything
• for variable width types, the offset vector should be all zeros before writing
• you must call setValueCount before a vector can be read
• you should never write to a vector once it has been read.

Please note that the current implementation doesn't enfore those rules, hence we may find few places that deviate from these rules (e.g. offset vectors in Variable Length and Repeated vector) This interface "should" strive to guarantee this order of operation:

allocate > mutate > setvaluecount > access > clear (or allocate to start the process over).

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ValueVector.Accessor An abstraction that is used to read from this vector instance.
static interface	ValueVector.Mutator An abstraction that is used to write into this vector instance.

Method Summary

Methods

Modifier and Type	Method and Description
void	allocateNew() Allocate new buffers.
boolean	allocateNewSafe() Allocates new buffers.
void	clear() Release the underlying ArrowBuf and reset the ValueVector to empty.
void	close() Alternative to clear().
ValueVector.Accessor	getAccessor() Returns an accessor that is used to read from this vector instance.
BufferAllocator	getAllocator()
ArrowBuf[]	getBuffers(boolean clear) Return the underlying buffers associated with this vector.
int	getBufferSize() Returns the number of bytes that is used by this vector instance.
int	getBufferSizeFor(int valueCount) Returns the number of bytes that is used by this vector if it holds the given number of values.
Field	getField() Get information about how this field is materialized.
Types.MinorType	getMinorType()
ValueVector.Mutator	getMutator() Returns an mutator that is used to write to this vector instance.
FieldReader	getReader() Returns a field reader that supports reading values from this vector.
TransferPair	getTransferPair(BufferAllocator allocator) Returns a transfer pair, creating a new target vector of the same type.
TransferPair	getTransferPair(String ref, BufferAllocator allocator)
int	getValueCapacity() Returns the maximum number of values that can be stored in this vector instance.
TransferPair	makeTransferPair(ValueVector target) Returns a new transfer pair that is used to transfer underlying buffers into the target vector.
void	setInitialCapacity(int numRecords) Set the initial record capacity

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

allocateNew

void allocateNew()
                 throws OutOfMemoryException

Allocate new buffers. ValueVector implements logic to determine how much to allocate.

Throws:

OutOfMemoryException - Thrown if no memory can be allocated.

allocateNewSafe

boolean allocateNewSafe()

Allocates new buffers. ValueVector implements logic to determine how much to allocate.

Returns:

Returns true if allocation was successful.

getAllocator

BufferAllocator getAllocator()

setInitialCapacity

void setInitialCapacity(int numRecords)

Set the initial record capacity

Parameters:

numRecords - the initial record capacity.

getValueCapacity

int getValueCapacity()

Returns the maximum number of values that can be stored in this vector instance.

close

void close()

Alternative to clear(). Allows use as an AutoCloseable in try-with-resources.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

clear

void clear()

Release the underlying ArrowBuf and reset the ValueVector to empty.

getField

Field getField()

Get information about how this field is materialized.

getMinorType

Types.MinorType getMinorType()

getTransferPair

TransferPair getTransferPair(BufferAllocator allocator)

Returns a transfer pair, creating a new target vector of the same type.

getTransferPair

TransferPair getTransferPair(String ref,
                           BufferAllocator allocator)

makeTransferPair

TransferPair makeTransferPair(ValueVector target)

Returns a new transfer pair that is used to transfer underlying buffers into the target vector.

getAccessor

ValueVector.Accessor getAccessor()

Returns an accessor that is used to read from this vector instance.

getMutator

ValueVector.Mutator getMutator()

Returns an mutator that is used to write to this vector instance.

getReader

FieldReader getReader()

Returns a field reader that supports reading values from this vector.

getBufferSize

int getBufferSize()

Returns the number of bytes that is used by this vector instance.

getBufferSizeFor

int getBufferSizeFor(int valueCount)

Returns the number of bytes that is used by this vector if it holds the given number of values. The result will be the same as if Mutator.setValueCount() were called, followed by calling getBufferSize(), but without any of the closing side-effects that setValueCount() implies wrt finishing off the population of a vector. Some operations might wish to use this to determine how much memory has been used by a vector so far, even though it is not finished being populated.

Parameters:

valueCount - the number of values to assume this vector contains

Returns:

the buffer size if this vector is holding valueCount values

getBuffers

ArrowBuf[] getBuffers(boolean clear)

Return the underlying buffers associated with this vector. Note that this doesn't impact the reference counts for this buffer so it only should be used for in-context access. Also note that this buffer changes regularly thus external classes shouldn't hold a reference to it (unless they change it).

Parameters:

clear - Whether to clear vector before returning; the buffers will still be refcounted; but the returned array will be the only reference to them

Returns:

The underlying buffers that is used by this vector instance.