@influxdata/influxdb3-client 2.2.0-nightly.16311 → 2.3.0

package/dist/index.d.mts

@@ -94,6 +94,11 @@ interface CommunicationObserver<T> {
     useResume?: (resume: () => void) => void;
 }
 
+interface PartialWriteLineError {
+    lineNumber: number;
+    errorMessage: string;
+    originalLine: string;
+}
 /** IllegalArgumentError is thrown when illegal argument is supplied. */
 declare class IllegalArgumentError extends Error {
     constructor(message: string);
@@ -113,6 +118,11 @@ declare class HttpError extends Error {
     json: any;
     constructor(statusCode: number, statusMessage: string | undefined, body?: string | undefined, contentType?: string | undefined | null, headers?: (HttpHeaders | null) | undefined, message?: string);
 }
+declare class PartialWriteError extends HttpError {
+    readonly lineErrors: PartialWriteLineError[];
+    constructor(statusCode: number, statusMessage: string | undefined, body: string | undefined, contentType: string | undefined | null, headers: HttpHeaders | null | undefined, message: string, lineErrors: PartialWriteLineError[]);
+    static fromHttpError(error: HttpError): PartialWriteError | undefined;
+}
 /** RequestTimedOutError indicates request timeout in the communication with the server */
 declare class RequestTimedOutError extends Error {
     constructor();
@@ -839,12 +849,29 @@ interface WriteOptions {
      * noSync=true means faster write but without the confirmation that the data was persisted.
      *
      * Note: This option is supported by InfluxDB 3 Core and Enterprise servers only.
-     * For other InfluxDB 3 server types (InfluxDB Clustered, InfluxDB Clould Serverless/Dedicated)
+     * For other InfluxDB 3 server types (InfluxDB Clustered, InfluxDB Cloud Dedicated/Serverless)
      * the write operation will fail with an error.
      *
      * Default value: false.
      */
     noSync?: boolean;
+    /**
+     * Controls partial-write behavior for writes sent to the V3 API endpoint
+     * (useV2Api=false).
+     * The client sends accept_partial=false only when set to false.
+     *
+     * For writes sent to the V2 API endpoint (useV2Api=true), this option is not used.
+     * Default value: true.
+     */
+    acceptPartial?: boolean;
+    /**
+     * Forces writes to the V2 API endpoint.
+     * Use this for InfluxDB Clustered and InfluxDB Cloud Dedicated/Serverless.
+     * For InfluxDB 3 Core/Enterprise, set useV2Api=false to write through the V3 API endpoint.
+     *
+     * Default value: true.
+     */
+    useV2Api?: boolean;
     /** default tags
      *
      * @example Default tags using client config
@@ -1038,9 +1065,26 @@ declare const convertTime: (value: string | number | Date | undefined, precision
  * - `string`: Represents lines of the [Line Protocol](https://bit.ly/2QL99fu).
  */
 type WritableData = ArrayLike<string> | ArrayLike<Point> | string | Point;
+/**
+ * Convert `WritableData` to an array of lines of
+ * [Line Protocol](https://bit.ly/2QL99fu)).
+ * If the data is an array of `Point` objects, it will be converted to lines of
+ * Line Protocol. If the data is a single `Point` object, it will be converted
+ * to a single line of Line Protocol. If the data is an array of lines of
+ * Line Protocol, it will be returned as is.
+ *
+ * @param data - data to write
+ * @param defaultTags - the default tags to apply to all points.
+ * @param tagOrder - preferred order of tags in line protocol serialization.
+ * Tags listed here are written first, in the same order.
+ * The remaining tags are appended in lexicographical order.
+ * This helps control first-write column order in InfluxDB 3.
+ * @param precision - the writing precision. It is used as the time precision
+ * when serializing Point instances whose timestamp is a Date
+ */
 declare const writableDataToLineProtocol: (data: WritableData, defaultTags?: {
     [key: string]: string;
-}, tagOrder?: string[]) => string[];
+}, tagOrder?: string[], precision?: WritePrecision) => string[];
 
 declare const collectAll: <T>(generator: AsyncGenerator<T, any, any>) => Promise<T[]>;
 /**
@@ -1075,7 +1119,9 @@ declare class InfluxDBClient {
      *   - timeout - I/O timeout
      *   - precision - timestamp precision when writing data
      *   - gzipThreshold - payload size threshold for gzipping data
+     *   - writeAcceptPartial - allow partial writes when some lines fail
      *   - writeNoSync - skip waiting for WAL persistence on write
+     *   - writeUseV2Api - use /api/v2/write V2 API endpoint
      *
      * @param connectionString - connection string
      */
@@ -1091,7 +1137,9 @@ declare class InfluxDBClient {
      *   - INFLUX_DATABASE - database (bucket) name
      *   - INFLUX_PRECISION - timestamp precision when writing data
      *   - INFLUX_GZIP_THRESHOLD - payload size threshold for gzipping data
+     *   - INFLUX_WRITE_ACCEPT_PARTIAL - allow partial writes when some lines fail
      *   - INFLUX_WRITE_NO_SYNC - skip waiting for WAL persistence on write
+     *   - INFLUX_WRITE_USE_V2_API - use /api/v2/write V2 API endpoint
      *   - INFLUX_GRPC_OPTIONS - comma separated set of key=value pairs matching @grpc/grpc-js channel options.
      */
     constructor();
@@ -1099,6 +1147,12 @@ declare class InfluxDBClient {
     private _mergeQueryOptions;
     /**
      * Write data into specified database.
+     *
+     * Warning: If only one Point is provided, and that Point
+     * contains fields with null/undefined values, those fields will not be written to InfluxDB.
+     * If such fields are later queried explicitly, for example,
+     * `SELECT field_with_value, field_with_null_value FROM my_table` an error will be thrown.
+     *
      * @param data - data to write
      * @param database - database to write into
      * @param org - organization to write into
@@ -1156,4 +1210,4 @@ declare class InfluxDBClient {
     close(): Promise<void>;
 }
 
-export { AbortError, type Cancellable, type ChunkCombiner, type ClientOptions, type CommunicationObserver, type ConnectionOptions, DEFAULT_ConnectionOptions, DEFAULT_QueryOptions, DEFAULT_WriteOptions, GetFieldTypeMissmatchError, type HttpHeaders as Headers, HttpError, type HttpHeaders, IllegalArgumentError, InfluxDBClient, Log, type Logger, Point, type PointFieldType, PointValues, type QParamType, type QueryOptions, type QueryType, RequestTimedOutError, type ResponseStartedFn, type SendOptions, type TimeConverter, type Transport, type WritableData, type WriteOptions, type WritePrecision, collectAll, consoleLogger, convertTime, convertTimeToNanos, createTextDecoderCombiner, currentTime, dateToProtocolTimestamp, escape, fromConnectionString, fromEnv, isNumber, parsePrecision, precisionToV2ApiString, precisionToV3ApiString, setLogger, useProcessHrtime, writableDataToLineProtocol };
+export { AbortError, type Cancellable, type ChunkCombiner, type ClientOptions, type CommunicationObserver, type ConnectionOptions, DEFAULT_ConnectionOptions, DEFAULT_QueryOptions, DEFAULT_WriteOptions, GetFieldTypeMissmatchError, type HttpHeaders as Headers, HttpError, type HttpHeaders, IllegalArgumentError, InfluxDBClient, Log, type Logger, PartialWriteError, type PartialWriteLineError, Point, type PointFieldType, PointValues, type QParamType, type QueryOptions, type QueryType, RequestTimedOutError, type ResponseStartedFn, type SendOptions, type TimeConverter, type Transport, type WritableData, type WriteOptions, type WritePrecision, collectAll, consoleLogger, convertTime, convertTimeToNanos, createTextDecoderCombiner, currentTime, dateToProtocolTimestamp, escape, fromConnectionString, fromEnv, isNumber, parsePrecision, precisionToV2ApiString, precisionToV3ApiString, setLogger, useProcessHrtime, writableDataToLineProtocol };

package/dist/index.d.ts

@@ -94,6 +94,11 @@ interface CommunicationObserver<T> {
     useResume?: (resume: () => void) => void;
 }
 
+interface PartialWriteLineError {
+    lineNumber: number;
+    errorMessage: string;
+    originalLine: string;
+}
 /** IllegalArgumentError is thrown when illegal argument is supplied. */
 declare class IllegalArgumentError extends Error {
     constructor(message: string);
@@ -113,6 +118,11 @@ declare class HttpError extends Error {
     json: any;
     constructor(statusCode: number, statusMessage: string | undefined, body?: string | undefined, contentType?: string | undefined | null, headers?: (HttpHeaders | null) | undefined, message?: string);
 }
+declare class PartialWriteError extends HttpError {
+    readonly lineErrors: PartialWriteLineError[];
+    constructor(statusCode: number, statusMessage: string | undefined, body: string | undefined, contentType: string | undefined | null, headers: HttpHeaders | null | undefined, message: string, lineErrors: PartialWriteLineError[]);
+    static fromHttpError(error: HttpError): PartialWriteError | undefined;
+}
 /** RequestTimedOutError indicates request timeout in the communication with the server */
 declare class RequestTimedOutError extends Error {
     constructor();
@@ -839,12 +849,29 @@ interface WriteOptions {
      * noSync=true means faster write but without the confirmation that the data was persisted.
      *
      * Note: This option is supported by InfluxDB 3 Core and Enterprise servers only.
-     * For other InfluxDB 3 server types (InfluxDB Clustered, InfluxDB Clould Serverless/Dedicated)
+     * For other InfluxDB 3 server types (InfluxDB Clustered, InfluxDB Cloud Dedicated/Serverless)
      * the write operation will fail with an error.
      *
      * Default value: false.
      */
     noSync?: boolean;
+    /**
+     * Controls partial-write behavior for writes sent to the V3 API endpoint
+     * (useV2Api=false).
+     * The client sends accept_partial=false only when set to false.
+     *
+     * For writes sent to the V2 API endpoint (useV2Api=true), this option is not used.
+     * Default value: true.
+     */
+    acceptPartial?: boolean;
+    /**
+     * Forces writes to the V2 API endpoint.
+     * Use this for InfluxDB Clustered and InfluxDB Cloud Dedicated/Serverless.
+     * For InfluxDB 3 Core/Enterprise, set useV2Api=false to write through the V3 API endpoint.
+     *
+     * Default value: true.
+     */
+    useV2Api?: boolean;
     /** default tags
      *
      * @example Default tags using client config
@@ -1038,9 +1065,26 @@ declare const convertTime: (value: string | number | Date | undefined, precision
  * - `string`: Represents lines of the [Line Protocol](https://bit.ly/2QL99fu).
  */
 type WritableData = ArrayLike<string> | ArrayLike<Point> | string | Point;
+/**
+ * Convert `WritableData` to an array of lines of
+ * [Line Protocol](https://bit.ly/2QL99fu)).
+ * If the data is an array of `Point` objects, it will be converted to lines of
+ * Line Protocol. If the data is a single `Point` object, it will be converted
+ * to a single line of Line Protocol. If the data is an array of lines of
+ * Line Protocol, it will be returned as is.
+ *
+ * @param data - data to write
+ * @param defaultTags - the default tags to apply to all points.
+ * @param tagOrder - preferred order of tags in line protocol serialization.
+ * Tags listed here are written first, in the same order.
+ * The remaining tags are appended in lexicographical order.
+ * This helps control first-write column order in InfluxDB 3.
+ * @param precision - the writing precision. It is used as the time precision
+ * when serializing Point instances whose timestamp is a Date
+ */
 declare const writableDataToLineProtocol: (data: WritableData, defaultTags?: {
     [key: string]: string;
-}, tagOrder?: string[]) => string[];
+}, tagOrder?: string[], precision?: WritePrecision) => string[];
 
 declare const collectAll: <T>(generator: AsyncGenerator<T, any, any>) => Promise<T[]>;
 /**
@@ -1075,7 +1119,9 @@ declare class InfluxDBClient {
      *   - timeout - I/O timeout
      *   - precision - timestamp precision when writing data
      *   - gzipThreshold - payload size threshold for gzipping data
+     *   - writeAcceptPartial - allow partial writes when some lines fail
      *   - writeNoSync - skip waiting for WAL persistence on write
+     *   - writeUseV2Api - use /api/v2/write V2 API endpoint
      *
      * @param connectionString - connection string
      */
@@ -1091,7 +1137,9 @@ declare class InfluxDBClient {
      *   - INFLUX_DATABASE - database (bucket) name
      *   - INFLUX_PRECISION - timestamp precision when writing data
      *   - INFLUX_GZIP_THRESHOLD - payload size threshold for gzipping data
+     *   - INFLUX_WRITE_ACCEPT_PARTIAL - allow partial writes when some lines fail
      *   - INFLUX_WRITE_NO_SYNC - skip waiting for WAL persistence on write
+     *   - INFLUX_WRITE_USE_V2_API - use /api/v2/write V2 API endpoint
      *   - INFLUX_GRPC_OPTIONS - comma separated set of key=value pairs matching @grpc/grpc-js channel options.
      */
     constructor();
@@ -1099,6 +1147,12 @@ declare class InfluxDBClient {
     private _mergeQueryOptions;
     /**
      * Write data into specified database.
+     *
+     * Warning: If only one Point is provided, and that Point
+     * contains fields with null/undefined values, those fields will not be written to InfluxDB.
+     * If such fields are later queried explicitly, for example,
+     * `SELECT field_with_value, field_with_null_value FROM my_table` an error will be thrown.
+     *
      * @param data - data to write
      * @param database - database to write into
      * @param org - organization to write into
@@ -1156,4 +1210,4 @@ declare class InfluxDBClient {
     close(): Promise<void>;
 }
 
-export { AbortError, type Cancellable, type ChunkCombiner, type ClientOptions, type CommunicationObserver, type ConnectionOptions, DEFAULT_ConnectionOptions, DEFAULT_QueryOptions, DEFAULT_WriteOptions, GetFieldTypeMissmatchError, type HttpHeaders as Headers, HttpError, type HttpHeaders, IllegalArgumentError, InfluxDBClient, Log, type Logger, Point, type PointFieldType, PointValues, type QParamType, type QueryOptions, type QueryType, RequestTimedOutError, type ResponseStartedFn, type SendOptions, type TimeConverter, type Transport, type WritableData, type WriteOptions, type WritePrecision, collectAll, consoleLogger, convertTime, convertTimeToNanos, createTextDecoderCombiner, currentTime, dateToProtocolTimestamp, escape, fromConnectionString, fromEnv, isNumber, parsePrecision, precisionToV2ApiString, precisionToV3ApiString, setLogger, useProcessHrtime, writableDataToLineProtocol };
+export { AbortError, type Cancellable, type ChunkCombiner, type ClientOptions, type CommunicationObserver, type ConnectionOptions, DEFAULT_ConnectionOptions, DEFAULT_QueryOptions, DEFAULT_WriteOptions, GetFieldTypeMissmatchError, type HttpHeaders as Headers, HttpError, type HttpHeaders, IllegalArgumentError, InfluxDBClient, Log, type Logger, PartialWriteError, type PartialWriteLineError, Point, type PointFieldType, PointValues, type QParamType, type QueryOptions, type QueryType, RequestTimedOutError, type ResponseStartedFn, type SendOptions, type TimeConverter, type Transport, type WritableData, type WriteOptions, type WritePrecision, collectAll, consoleLogger, convertTime, convertTimeToNanos, createTextDecoderCombiner, currentTime, dateToProtocolTimestamp, escape, fromConnectionString, fromEnv, isNumber, parsePrecision, precisionToV2ApiString, precisionToV3ApiString, setLogger, useProcessHrtime, writableDataToLineProtocol };