@langchain/community
Version:
Third-party integrations for LangChain.js
1 lines • 28.1 kB
Source Map (JSON)
{"version":3,"file":"cassandra.d.cts","names":["AsyncCallerParams","Client","DseClientOptions","types","driverTypes","AstraServiceProviderArgs","URL","CassandraServiceProviderArgs","CassandraClientArgs","CassandraClientFactory","Promise","Column","Index","Filter","WhereClause","Record","CassandraTableArgs","CassandraTable","ResultSet"],"sources":["../../src/utils/cassandra.d.ts"],"sourcesContent":["import { AsyncCallerParams } from \"@langchain/core/utils/async_caller\";\nimport { Client, DseClientOptions, types as driverTypes } from \"cassandra-driver\";\n/**\n * Defines the configuration options for connecting to Astra DB, DataStax's cloud-native Cassandra-as-a-Service.\n * This interface specifies the necessary parameters required to establish a connection with an Astra DB instance,\n * including authentication and targeting specific data centers or regions.\n *\n * Properties:\n * - `token`: The authentication token required for accessing the Astra DB instance. Essential for establishing a secure connection.\n * - `endpoint`: Optional. The URL or network address of the Astra DB instance. Can be used to directly specify the connection endpoint.\n * - `datacenterID`: Optional. The unique identifier of the data center to connect to. Used to compute the endpoint.\n * - `regionName`: Optional. The region name of the Astra DB instance. Used to compute the endpoint. Default to the primary region.\n * - `bundleUrlTemplate`: Optional. The URL template for downloading the secure connect bundle. Used to customize the bundle URL. \"database_id\" variable will be resolved at runtime.\n *\n * Either `endpoint` or `datacenterID` must be provided to establish a connection to Astra DB.\n */\nexport interface AstraServiceProviderArgs {\n token: string;\n endpoint?: string | URL;\n datacenterID?: string;\n regionName?: string;\n bundleUrlTemplate?: string;\n}\n/**\n * Encapsulates the service provider-specific arguments required for creating a Cassandra client.\n * This interface acts as a wrapper for configurations pertaining to various Cassandra service providers,\n * allowing for extensible and flexible client configuration.\n *\n * Currently, it supports:\n * - `astra`: Optional. Configuration parameters specific to Astra DB, DataStax's cloud-native Cassandra service.\n * Utilizing this property enables tailored connections to Astra DB instances with custom configurations.\n *\n * This structure is designed to be extended with additional service providers in the future, ensuring adaptability\n * and extensibility for connecting to various Cassandra services with distinct configuration requirements.\n */\nexport interface CassandraServiceProviderArgs {\n astra?: AstraServiceProviderArgs;\n}\n/**\n * Extends the DataStax driver's client options with additional configurations for service providers,\n * enabling the customization of Cassandra client instances based on specific service requirements.\n * This interface integrates native driver configurations with custom extensions, facilitating the\n * connection to Cassandra databases, including managed services like Astra DB.\n *\n * - `serviceProviderArgs`: Optional. Contains the connection arguments for specific Cassandra service providers,\n * such as Astra DB. This allows for detailed and service-specific client configurations,\n * enhancing connectivity and functionality across different Cassandra environments.\n *\n * Incorporating this interface into client creation processes ensures a comprehensive setup, encompassing both\n * standard and extended options for robust and versatile Cassandra database interactions.\n */\nexport interface CassandraClientArgs extends DseClientOptions {\n serviceProviderArgs?: CassandraServiceProviderArgs;\n}\n/**\n * Provides a centralized and streamlined factory for creating and configuring instances of the Cassandra client.\n * This class abstracts the complexities involved in instantiating and configuring Cassandra client instances,\n * enabling straightforward integration with Cassandra databases. It supports customization through various\n * configuration options, allowing for the creation of clients tailored to specific needs, such as connecting\n * to different clusters or utilizing specialized authentication and connection options.\n *\n * Key Features:\n * - Simplifies the Cassandra client creation process with method-based configurations.\n * - Supports customization for connecting to various Cassandra environments, including cloud-based services like Astra.\n * - Ensures consistent and optimal client configuration, incorporating best practices.\n *\n * Example Usage (Apache Cassandra®):\n * ```\n * const cassandraArgs = {\n * contactPoints: ['h1', 'h2'],\n * localDataCenter: 'datacenter1',\n * credentials: {\n * username: <...> as string,\n * password: <...> as string,\n * },\n * };\n * const cassandraClient = CassandraClientFactory.getClient(cassandraArgs);\n * ```\n *\n * Example Usage (DataStax AstraDB):\n * ```\n * const astraArgs = {\n * serviceProviderArgs: {\n * astra: {\n * token: <...> as string,\n * endpoint: <...> as string,\n * },\n * },\n * };\n * const cassandraClient = CassandraClientFactory.getClient(astraArgs);\n * ``` *\n */\nexport declare class CassandraClientFactory {\n /**\n * Asynchronously obtains a configured Cassandra client based on the provided arguments.\n * This method processes the given CassandraClientArgs to produce a configured Client instance\n * from the cassandra-driver, suitable for interacting with Cassandra databases.\n *\n * @param args The configuration arguments for the Cassandra client, including any service provider-specific options.\n * @returns A Promise resolving to a Client object configured according to the specified arguments.\n */\n static getClient(args: CassandraClientArgs): Promise<Client>;\n /**\n * Processes the provided CassandraClientArgs for creating a Cassandra client.\n *\n * @param args The arguments for creating the Cassandra client, including service provider configurations.\n * @returns A Promise resolving to the processed CassandraClientArgs, ready for client initialization.\n * @throws Error if the configuration is unsupported, specifically if serviceProviderArgs are provided\n * but do not include valid configurations for Astra.\n */\n private static processArgs;\n private static processAstraArgs;\n private static getAstraDefaultBundleLocation;\n private static setAstraBundle;\n private static downloadAstraSecureConnectBundle;\n}\n/**\n * Represents the definition of a column within a Cassandra table schema.\n * This interface is used to specify the properties of table columns during table creation\n * and to define how columns are utilized in select queries.\n *\n * Properties:\n * - `name`: The name of the column.\n * - `type`: The data type of the column, used during table creation to define the schema.\n * - `partition`: Optional. Specifies whether the column is part of the partition key. Important for table creation.\n * - `alias`: Optional. An alias for the column that can be used in select queries for readability or to avoid naming conflicts.\n * - `binds`: Optional. Specifies values to be bound to the column in queries, supporting parameterized query construction.\n *\n */\nexport interface Column {\n name: string;\n type: string;\n partition?: boolean;\n alias?: string;\n binds?: unknown | [unknown, ...unknown[]];\n}\n/**\n * Defines an index on a Cassandra table column, facilitating efficient querying by column values.\n * This interface specifies the necessary configuration for creating secondary indexes on table columns,\n * enhancing query performance and flexibility.\n *\n * Properties:\n * - `name`: The name of the index. Typically related to the column it indexes for clarity.\n * - `value`: The name of the column on which the index is created.\n * - `options`: Optional. Custom options for the index, specified as a string. This can include various index\n * configurations supported by Cassandra, such as using specific indexing classes or options.\n *\n */\nexport interface Index {\n name: string;\n value: string;\n options?: string;\n}\n/**\n * Represents a filter condition used in constructing WHERE clauses for querying Cassandra tables.\n * Filters specify the criteria used to select rows from a table, based on column values.\n *\n * Properties:\n * - `name`: The name of the column to filter on.\n * - `value`: The value(s) to match against the column. Can be a single value or an array of values for operations like IN.\n * - `operator`: Optional. The comparison operator to use (e.g., '=', '<', '>', 'IN'). Defaults to '=' if not specified.\n *\n */\nexport interface Filter {\n name: string;\n value: unknown | [unknown, ...unknown[]];\n operator?: string;\n}\n/**\n * Defines a type for specifying WHERE clause conditions in Cassandra queries.\n * This can be a single `Filter` object, an array of `Filter` objects for multiple conditions,\n * or a `Record<string, unknown>` for simple equality conditions keyed by column name.\n */\nexport type WhereClause = Filter[] | Filter | Record<string, unknown>;\n/**\n * Defines the configuration arguments for initializing a Cassandra table within an application.\n * This interface extends `AsyncCallerParams`, incorporating asynchronous operation configurations,\n * and adds specific properties for table creation, query execution, and data manipulation in a\n * Cassandra database context.\n *\n * Properties:\n * - `table`: The name of the table to be used or created.\n * - `keyspace`: The keyspace within which the table exists or will be created.\n * - `primaryKey`: Specifies the column(s) that constitute the primary key of the table. This can be a single\n * `Column` object for a simple primary key or an array of `Column` objects for composite keys.\n * - `nonKeyColumns`: Defines columns that are not part of the primary key. Similar to `primaryKey`, this can be a\n * single `Column` object or an array of `Column` objects, supporting flexible table schema definitions.\n * - `withClause`: Optional. A string containing additional CQL table options to be included in the CREATE TABLE statement.\n * This enables the specification of various table behaviors and properties, such as compaction strategies\n * and TTL settings.\n * - `indices`: Optional. An array of `Index` objects defining secondary indices on the table for improved query performance\n * on non-primary key columns.\n * - `batchSize`: Optional. Specifies the default size of batches for batched write operations to the table, affecting\n * performance and consistency trade-offs.\n *\n */\nexport interface CassandraTableArgs extends AsyncCallerParams {\n table: string;\n keyspace: string;\n primaryKey: Column | Column[];\n nonKeyColumns: Column | Column[];\n withClause?: string;\n indices?: Index[];\n batchSize?: number;\n}\n/**\n * Represents a Cassandra table, encapsulating functionality for schema definition, data manipulation, and querying.\n * This class provides a high-level abstraction over Cassandra's table operations, including creating tables,\n * inserting, updating, selecting, and deleting records. It leverages the CassandraClient for executing\n * operations and supports asynchronous interactions with the database.\n *\n * Key features include:\n * - Table and keyspace management: Allows for specifying table schema, including primary keys, columns,\n * and indices, and handles the creation of these elements within the specified keyspace.\n * - Data manipulation: Offers methods for inserting (upserting) and deleting data in batches or individually,\n * with support for asynchronous operation and concurrency control.\n * - Querying: Enables selecting data with flexible filtering, sorting, and pagination options.\n *\n * The class is designed to be instantiated with a set of configuration arguments (`CassandraTableArgs`)\n * that define the table's structure and operational parameters, providing a streamlined interface for\n * interacting with Cassandra tables in a structured and efficient manner.\n *\n * Usage Example:\n * ```typescript\n * const tableArgs: CassandraTableArgs = {\n * table: 'my_table',\n * keyspace: 'my_keyspace',\n * primaryKey: [{ name: 'id', type: 'uuid', partition: true }],\n * nonKeyColumns: [{ name: 'data', type: 'text' }],\n * };\n * const cassandraClient = new CassandraClient(clientConfig);\n * const myTable = new CassandraTable(tableArgs, cassandraClient);\n * ```\n *\n * This class simplifies Cassandra database interactions, making it easier to perform robust data operations\n * while maintaining clear separation of concerns and promoting code reusability.\n */\nexport declare class CassandraTable {\n private client;\n private readonly keyspace;\n private readonly table;\n private primaryKey;\n private nonKeyColumns;\n private indices;\n private withClause;\n private batchSize;\n private initializationPromise;\n private asyncCaller;\n private constructorArgs;\n /**\n * Initializes a new instance of the CassandraTable class with specified configuration.\n * This includes setting up the table schema (primary key, columns, and indices) and\n * preparing the environment for executing queries against a Cassandra database.\n *\n * @param args Configuration arguments defining the table schema and operational settings.\n * @param client Optional. A Cassandra Client instance. If not provided, one will be created\n * using the configuration specified in `args`.\n */\n constructor(args: CassandraTableArgs, client?: Client);\n /**\n * Executes a SELECT query on the Cassandra table with optional filtering, ordering, and pagination.\n * Allows for specifying columns to return, filter conditions, sort order, and limits on the number of results.\n *\n * @param columns Optional. Columns to include in the result set. If omitted, all columns are selected.\n * @param filter Optional. Conditions to apply to the query for filtering results.\n * @param orderBy Optional. Criteria to sort the result set.\n * @param limit Optional. Maximum number of records to return.\n * @param allowFiltering Optional. Enables ALLOW FILTERING option for queries that cannot be executed directly due to Cassandra's query restrictions.\n * @param fetchSize Optional. The number of rows to fetch per page (for pagination).\n * @param pagingState Optional. The paging state from a previous query execution, used for pagination.\n * @returns A Promise resolving to the query result set.\n */\n select(columns?: Column[], filter?: WhereClause, orderBy?: Filter[], limit?: number, allowFiltering?: boolean, fetchSize?: number, pagingState?: string): Promise<driverTypes.ResultSet>;\n /**\n * Validates the correspondence between provided values and specified columns for database operations.\n * This method checks if the number of values matches the number of specified columns, ensuring\n * data integrity before executing insert or update operations. It also defaults to using all table columns\n * if specific columns are not provided. Throws an error if the validation fails.\n *\n * @param values An array of values or an array of arrays of values to be inserted or updated. Each\n * inner array represents a set of values corresponding to one row in the table.\n * @param columns Optional. An array of `Column` objects specifying the columns to be used for the operation.\n * If not provided, the method defaults to using both primary key and non-key columns of the table.\n * @returns An array of `Column` objects that have been validated for the operation.\n * @throws Error if the number of provided values does not match the number of specified columns.\n * @private\n */\n private _columnCheck;\n /**\n * Inserts or updates records in the Cassandra table in batches, managing concurrency and batching size.\n * This method organizes the provided values into batches and uses `_upsert` to perform the database operations.\n *\n * @param values An array of arrays, where each inner array contains values for a single record.\n * @param columns Optional. Columns to be included in the insert/update operations. Defaults to all table columns.\n * @param batchSize Optional. The size of each batch for the operation. Defaults to the class's batchSize property.\n * @returns A Promise that resolves once all records have been upserted.\n */\n upsert(values: unknown[][], columns?: Column[], batchSize?: number): Promise<void>;\n /**\n * Deletes rows from the Cassandra table that match the specified WHERE clause conditions.\n *\n * @param whereClause Defines the conditions that must be met for rows to be deleted. Can be a single filter,\n * an array of filters, or a key-value map translating to filter conditions.\n * @returns A Promise that resolves when the DELETE operation has completed.\n */\n delete(whereClause: WhereClause): Promise<driverTypes.ResultSet>;\n /**\n * Retrieves the Node.js Cassandra client instance associated with this table.\n * This method ensures that the client is initialized and ready for use, returning the\n * Cassandra client object that can be used for database operations directly.\n * It initializes the client if it has not already been initialized.\n *\n * @returns A Promise that resolves to the Cassandra Client instance used by this table for database interactions.\n */\n getClient(): Promise<Client>;\n /**\n * Constructs the PRIMARY KEY clause for a Cassandra CREATE TABLE statement based on the specified columns.\n * This method organizes the provided columns into partition and clustering keys, forming the necessary syntax\n * for the PRIMARY KEY clause in a Cassandra table schema definition. It supports complex primary key structures,\n * including composite partition keys and clustering columns.\n *\n * - Partition columns are those marked with the `partition` property. If multiple partition columns are provided,\n * they are grouped together in parentheses as a composite partition key.\n * - Clustering columns are those not marked as partition keys and are listed after the partition key(s).\n * They determine the sort order of rows within a partition.\n *\n * The method ensures the correct syntax for primary keys, handling both simple and composite key structures,\n * and throws an error if no partition or clustering columns are provided.\n *\n * @param columns An array of `Column` objects representing the columns to be included in the primary key.\n * Each column must have a `name` and may have a `partition` boolean indicating if it is part\n * of the partition key.\n * @returns The PRIMARY KEY clause as a string, ready to be included in a CREATE TABLE statement.\n * @throws Error if no columns are marked as partition keys or if no columns are provided.\n * @private\n */\n private buildPrimaryKey;\n /**\n * Type guard that checks if a given object conforms to the `Filter` interface.\n * This method is used to determine if an object can be treated as a filter for Cassandra\n * query conditions. It evaluates the object's structure, specifically looking for `name`\n * and `value` properties, which are essential for defining a filter in Cassandra queries.\n *\n * @param obj The object to be evaluated.\n * @returns A boolean value indicating whether the object is a `Filter`. Returns `true`\n * if the object has both `name` and `value` properties, signifying it meets the\n * criteria for being used as a filter in database operations; otherwise, returns `false`.\n * @private\n */\n private isFilter;\n /**\n * Helper to convert Record<string,unknown> to a Filter[]\n * @param record: a key-value Record collection\n * @returns Record as a Filter[]\n */\n private convertToFilters;\n /**\n * Converts a key-value pair record into an array of `Filter` objects suitable for Cassandra query conditions.\n * This utility method allows for a more flexible specification of filter conditions by transforming\n * a simple object notation into the structured format expected by Cassandra query builders. Each key-value\n * pair in the record is interpreted as a filter condition, where the key represents the column name and\n * the value represents the filtering criterion.\n *\n * The method assumes a default equality operator for each filter. It is particularly useful for\n * converting concise filter specifications into the detailed format required for constructing CQL queries.\n *\n * @param record A key-value pair object where each entry represents a filter condition, with the key\n * as the column name and the value as the filter value. The value can be a single value\n * or an array to support IN queries with multiple criteria.\n * @returns An array of `Filter` objects, each representing a condition extracted from the input record.\n * The array can be directly used in constructing query WHERE clauses.\n * @private\n */\n private asFilters;\n /**\n * Constructs the WHERE clause of a CQL query from an array of `Filter` objects.\n * This method generates the conditional part of a Cassandra Query Language (CQL) statement,\n * allowing for complex query constructions based on provided filters. Each filter in the array\n * translates into a condition within the WHERE clause, with support for various comparison operators.\n *\n * The method handles the assembly of these conditions into a syntactically correct CQL WHERE clause,\n * including the appropriate use of placeholders (?) for parameter binding in prepared statements.\n * It supports a range of operators, defaulting to \"=\" (equality) if an operator is not explicitly specified\n * in a filter. Filters with multiple values (e.g., for IN conditions) are also correctly formatted.\n *\n * @param filters Optional. An array of `Filter` objects representing the conditions to apply in the WHERE clause.\n * Each `Filter` includes a column name (`name`), a value or array of values (`value`), and optionally,\n * an operator (`operator`). If no filters are provided, an empty string is returned.\n * @returns The constructed WHERE clause as a string, ready to be appended to a CQL query. If no filters\n * are provided, returns an empty string, indicating no WHERE clause should be applied.\n * @private\n */\n private buildWhereClause;\n /**\n * Generates the ORDER BY clause for a CQL query from an array of `Filter` objects.\n * This method forms the sorting part of a Cassandra Query Language (CQL) statement,\n * allowing for detailed control over the order of results based on specified column names\n * and directions. Each filter in the array represents a column and direction to sort by.\n *\n * It is important to note that unlike the traditional use of `Filter` objects for filtering,\n * in this context, they are repurposed to specify sorting criteria. The `name` field indicates\n * the column to sort by, and the `operator` field is used to specify the sort direction (`ASC` or `DESC`).\n * The `value` field is not utilized for constructing the ORDER BY clause and can be omitted.\n *\n * @param filters Optional. An array of `Filter` objects where each object specifies a column and\n * direction for sorting. The `name` field of each filter represents the column name,\n * and the `operator` field should contain the sorting direction (`ASC` or `DESC`).\n * If no filters are provided, the method returns an empty string.\n * @returns The constructed ORDER BY clause as a string, suitable for appending to a CQL query.\n * If no sorting criteria are provided, returns an empty string, indicating no ORDER BY\n * clause should be applied to the query.\n * @private\n */\n private buildOrderByClause;\n /**\n * Constructs a CQL search query string for retrieving records from a Cassandra table.\n * This method combines various query components, including selected columns, filters, sorting criteria,\n * and pagination options, to form a complete and executable CQL query. It allows for fine-grained control\n * over the query construction process, enabling the inclusion of conditional filtering, ordering of results,\n * and limiting the number of returned records, with an optional allowance for filtering.\n *\n * The method meticulously constructs the SELECT part of the query using the provided columns, applies\n * the WHERE clause based on given filters, sorts the result set according to the orderBy criteria, and\n * restricts the number of results with the limit parameter. Additionally, it can enable the ALLOW FILTERING\n * option for queries that require server-side filtering beyond the capabilities of primary and secondary indexes.\n *\n * @param queryColumns An array of `Column` objects specifying which columns to include in the result set.\n * Each column can also have an alias defined for use in the query's result set.\n * @param filters Optional. An array of `Filter` objects to apply as conditions in the WHERE clause of the query.\n * @param orderBy Optional. An array of `Filter` objects specifying the ordering of the returned records.\n * Although repurposed as `Filter` objects, here they define the column names and the sort direction (ASC/DESC).\n * @param limit Optional. A numeric value specifying the maximum number of records the query should return.\n * @param allowFiltering Optional. A boolean flag that, when true, includes the ALLOW FILTERING clause in the query,\n * permitting Cassandra to execute queries that might not be efficiently indexable.\n * @returns A string representing the fully constructed CQL search query, ready for execution against a Cassandra table.\n * @private\n */\n private buildSearchQuery;\n private initialize;\n private performInitialization;\n private _upsert;\n}\n//# sourceMappingURL=cassandra.d.ts.map"],"mappings":";;;;;;;AAgBA;AAmBA;AAgBA;AAyCA;;;;AASwD;AA4BxD;AAmBA;AAeA;AAUA;AAA0Ba,UA7JTR,wBAAAA,CA6JSQ;EAAWA,KAAAA,EAAAA,MAAAA;EAASE,QAAAA,CAAAA,EAAAA,MAAAA,GA3JtBT,GA2JsBS;EAAM,YAAA,CAAA,EAAA,MAAA;EAuBnCC,UAAAA,CAAAA,EAAAA,MAAAA;EAGDL,iBAAAA,CAAAA,EAAAA,MAAAA;;;;;;AAH6C;AAyC7D;;;;;;;AAmC8JD,UA7O7IH,4BAAAA,CA6O6IG;EAyBpHC,KAAAA,CAAAA,EArQ9BN,wBAqQ8BM;;;;;;;AAiBlB;;;;;;;;UAvQPH,mBAAAA,SAA4BN;wBACnBK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAwCLE,sBAAAA;;;;;;;;;yBASMD,sBAAsBE,QAAQT;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA4BxCU,MAAAA;;;;;;;;;;;;;;;;;;;UAmBAC,KAAAA;;;;;;;;;;;;;;;UAeAC,MAAAA;;;;;;;;;;KAULC,WAAAA,GAAcD,WAAWA,SAASE;;;;;;;;;;;;;;;;;;;;;;;UAuB7BC,kBAAAA,SAA2BhB;;;cAG5BW,SAASA;iBACNA,SAASA;;YAEdC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmCOK,cAAAA;;;;;;;;;;;;;;;;;;;;;oBAqBCD,6BAA6Bf;;;;;;;;;;;;;;mBAc9BU,mBAAmBG,uBAAuBD,+FAA+FH,QAAQN,KAAAA,CAAYc;;;;;;;;;;;;;;;;;;;;;;;;;wCAyBxIP,+BAA+BD;;;;;;;;sBAQjDI,cAAcJ,QAAQN,KAAAA,CAAYc;;;;;;;;;eASzCR,QAAQT"}