 |
C++ SDK Documentation
24.2.0
|
|
C++ SDK Documentation
24.2.0
|
Parses an input stream into Vertica tuples (rows to be inserted into a table). More...
Public Member Functions | |
| void | cancelUDX (ServerInterface &srvInterface) |
| virtual void | destroy (ServerInterface &srvInterface, SizedColumnTypes &returnType) |
| virtual void | destroy (ServerInterface &srvInterface, SizedColumnTypes &returnType, SessionParamWriterMap &udSessionParams) |
| virtual RejectedRecord | getRejectedRecord () |
| bool | isCanceled () const |
| virtual bool | isReadyToCooperate (ServerInterface &srvInterface) |
| virtual void | prepareToCooperate (ServerInterface &srvInterface, bool isLeader) |
| virtual StreamState | process (ServerInterface &srvInterface, DataBuffer &input, InputState input_state)=0 |
| virtual StreamState | processWithMetadata (ServerInterface &srvInterface, DataBuffer &input, LengthBuffer &input_lengths, InputState input_state) |
| virtual void | setup (ServerInterface &srvInterface, SizedColumnTypes &returnType) |
| virtual bool | useSideChannel () |
Protected Member Functions | |
| virtual void | cancel (ServerInterface &srvInterface) |
| Portion | getPortion () |
Protected Attributes | |
| Portion | portion |
| vint | recordsAcceptedInBatch |
| bool | seen_eob |
| std::string | srcname |
| StreamWriter * | writer |
Parses an input stream into Vertica tuples (rows to be inserted into a table).
A UDParser can be used with up to one UDSource and any number of UDfilters.
Note that it is UNSAFE to maintain pointers or references to any of these arguments (or any other argument passed by reference into any other function in this API) beyond the scope of the function call in question. For example, do not store a reference to the server interface or the input block on an instance variable. Vertica may free and replace these objects.
|
inlineprotectedvirtualinherited |
Cancel callback to be overridden by the UDX. Called when the query running the UDX has been canceled.
Referenced by Vertica::UDXObject::cancelUDX().
|
inlineinherited |
Cancel callback invoked when the query running the UDX has been canceled. See cancel().
|
inlinevirtual |
Will be invoked during query execution, after the last time that process() is called on this UDParser instance for a particular input file.
May optionally be overridden to perform tear-down/destruction.
See UDParser::setup() for a note about the restartability of UDParsers.
|
inlineprotected |
Return a description of the portion of the input source which is being processed by the active load stack. This can be called by the UDParser implementation to determine how much data to process.
This can be invoked during setup(), process() or destroy().
The Portion object returned will be a valid portion if any part of the load stack is processing portions. This UDParser instance will see input states START_OF_PORTION and/or END_OF_PORTION if it is the stack element directly processing portions.
|
inlinevirtual |
Returns information about the rejected record
|
inlineinherited |
|
inlinevirtual |
UDParser::isReadyToCooperate()
Called after UDParser::prepareToCooperate(), returns false if this parser is not yet ready to cooperate. Once this method returns true the parser can begin to cooperate. Default implementation returns true, override if some preparation is required before the parser can cooperate (e.g. a certain # of rows must be skipped).
|
inlinevirtual |
UDParser::prepareToCooperate()
Notification to this parser that it should prepare to share parsing input with another. This can only happen when a parser has an associated chunker. Default implementation does nothing.
|
pure virtual |
Reads data from the input stream and produces tuples to load. Vertica invokes this method repeatedly during query execution until it returns DONE, or until the query is canceled by the user.
Input: a stream of bytes.
Output: a stream of tuples.
On each invocation, process() is given an input buffer. It must read data from the input buffer, convert the data to fields and tuples, then write those tuples with writer. After it has consumed as much as it reasonably can (for example, after it consumes the last complete row in the input buffer), it must return INPUT_NEEDED to indicate that more data is needed, or DONE to indicate that it has completed parsing the input stream and will not read more bytes.
If input_state == END_OF_FILE, then the last byte in input is the last byte in the input stream. Returning INPUT_NEEDED does not result in any new input. In this case, process() must return DONE as soon as this operator finishes producing all output that it is going to produce.
Note that input might contain null bytes, if the source file contains null bytes. Additionally, note that input is NOT automatically null-terminated.
process() must not block indefinitely. If it cannot proceed for an extended period of time, it should return KEEP_GOING so that it can be called again. Failure to do this causes issues, including preventing the user from canceling the query.
Note that unless INPUT_NEEDED is returned, input is UNMODIFIED the next time process() is called. This means that pointers into the buffer are still valid. It also means that input.offset may be set. In general, process() code should assume that buffers start at input.buf[input.offset].
Row Rejection
process() can "reject" a row, which logs it using Vertica's rejected-rows mechanism. Rejected rows should not be emitted as tuples. All previous input must have been consumed by a call to process(). To reject a row, set input.offset to the position of the row, and return REJECT.
Referenced by processWithMetadata().
|
inlinevirtual |
UDParser::processWithMetadata()
Reads data from the input stream and record length metadata from the side channel and produces tuples to load. To implement processWithMetadata(), you must override useSideChannel() to return true. Vertica invokes this method repeately during query execution until it returns DONE, or until the query is canceled by the user.
Input: a stream of data bytes, and a stream of bytes containing message length metadata.
Output: a stream of tuples.
On each invocation, processWithMetadata() is given an input buffer and a length buffer. It must read data from the input buffer and metadata from the length buffer, convert the data to fields and tuples, then write the tuples with writer. After it has consumed as much as it reasonably can (for example, after it consumes the last complete row in the input buffer), it must return INPUT_NEEDED to indicate that more data is needed, or DONE to indicate that parsing this input stream is complete and it will not read any more bytes.
If input_state == END_OF_FILE, then the last byte in input is the last byte in the input stream. Returning INPUT_NEEDED does not result in any new input. In this case, processWithMetadata() must return DONE as soon as this operator finishes producing all output that it is going to produce.
Note that input might contain null bytes if the source file contains null bytes. Additionally, note that input are NOT automatically null-terminated.
processWithMetadata() must not block indefinitely. If it cannot proceed for an extended period of time, it should return KEEP_GOING so that it can be called again. Failure to do this causes issues, including preventing the user from canceling the query.
In general, processWithMetadata() code should assume that the DataBuffer starts at input.buf[input.offset] and the LengthBuffer starts at `input_lengths.buf[input_lengths.offset].
Row Rejection
processWithMetadata() can "reject" a row, which logs it using Vertica's rejected-rows mechanism. Rejected rows should not be emitted as tuples. All previous input must have been consumed by a call to process(). To reject a row, set input.offset to the position of the row, and return REJECT.
|
inlinevirtual |
Will be invoked during query execution, prior to the first time that process() is called on this UDParser instance for a particular input source.
May optionally be overridden to perform setup/initialzation.
Note that UDParsers MUST BE RESTARTABLE! If loading large numbers of files, a given UDParsers may be re-used for multiple files. Vertica follows the worker-pool design pattern: At the start of COPY execution, several Parsers and several Filters are instantiated per node, by calling the corresponding prepare() method multiple times. Each Filter/Parser pair is then internally assigned to an initial Source (UDSource or internal). At that point, setup() is called; then process() is called until it is finished; then destroy() is called. If there are still sources in the pool waiting to be processed, then the UDFilter/UDSource pair will be given a second Source; setup() will be called a second time, then process() until it is finished, then destroy(). This repeats until all sources have been read.
|
inlinevirtual |
Provides access to the side channel containing record length metadata, when the data source has metadata about record boundaries available in a structured format that is separate from the data payload, and it is retained throughout the load stack.
Override and return true to indicate that processWithMetadata() should be called instead of process().
Return false to implement process()
false by default.
|
protected |
Writer to write parsed tuples to. Has the same API as PartitionWriter, from the UDT framework.