pipework 0.252.0 → 0.252.1

package/src/data/query/sql/expressions/index.ts

@@ -0,0 +1,2 @@
+export * from './conditions.js';
+export * from './select.js';

package/src/data/query/sql/expressions/select.ts

@@ -0,0 +1,45 @@
+import type { AnyColumn } from '../../column.js';
+import type { SQL, SQLWrapper } from '../sql.js';
+import { sql } from '../sql.js';
+
+/**
+ * Used in sorting, this specifies that the given
+ * column or expression should be sorted in ascending
+ * order. By the SQL standard, ascending order is the
+ * default, so it is not usually necessary to specify
+ * ascending sort order.
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // Return cars, starting with the oldest models
+ * // and going in ascending order to the newest.
+ * db.select().from(cars)
+ *   .orderBy(asc(cars.year));
+ * ```
+ *
+ * @see desc to sort in descending order
+ */
+export function asc(column: AnyColumn | SQLWrapper): SQL {
+	return sql`${column} asc`;
+}
+
+/**
+ * Used in sorting, this specifies that the given
+ * column or expression should be sorted in descending
+ * order.
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // Select users, with the most recently created
+ * // records coming first.
+ * db.select().from(users)
+ *   .orderBy(desc(users.createdAt));
+ * ```
+ *
+ * @see asc to sort in ascending order
+ */
+export function desc(column: AnyColumn | SQLWrapper): SQL {
+	return sql`${column} desc`;
+}

package/src/data/query/sql/functions/aggregate.ts

@@ -0,0 +1,129 @@
+import { type AnyColumn, Column } from '../../column.js';
+import { is } from '../../entity.js';
+import { type SQL, sql, type SQLWrapper } from '../sql.js';
+
+/**
+ * Returns the number of values in `expression`.
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // Number employees with null values
+ * db.select({ value: count() }).from(employees)
+ * // Number of employees where `name` is not null
+ * db.select({ value: count(employees.name) }).from(employees)
+ * ```
+ *
+ * @see countDistinct to get the number of non-duplicate values in `expression`
+ */
+export function count(expression?: SQLWrapper): SQL<number> {
+	return sql`count(${expression || sql.raw('*')})`.mapWith(Number);
+}
+
+/**
+ * Returns the number of non-duplicate values in `expression`.
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // Number of employees where `name` is distinct
+ * db.select({ value: countDistinct(employees.name) }).from(employees)
+ * ```
+ *
+ * @see count to get the number of values in `expression`, including duplicates
+ */
+export function countDistinct(expression: SQLWrapper): SQL<number> {
+	return sql`count(distinct ${expression})`.mapWith(Number);
+}
+
+/**
+ * Returns the average (arithmetic mean) of all non-null values in `expression`.
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // Average salary of an employee
+ * db.select({ value: avg(employees.salary) }).from(employees)
+ * ```
+ *
+ * @see avgDistinct to get the average of all non-null and non-duplicate values in `expression`
+ */
+export function avg(expression: SQLWrapper): SQL<string | null> {
+	return sql`avg(${expression})`.mapWith(String);
+}
+
+/**
+ * Returns the average (arithmetic mean) of all non-null and non-duplicate values in `expression`.
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // Average salary of an employee where `salary` is distinct
+ * db.select({ value: avgDistinct(employees.salary) }).from(employees)
+ * ```
+ *
+ * @see avg to get the average of all non-null values in `expression`, including duplicates
+ */
+export function avgDistinct(expression: SQLWrapper): SQL<string | null> {
+	return sql`avg(distinct ${expression})`.mapWith(String);
+}
+
+/**
+ * Returns the sum of all non-null values in `expression`.
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // Sum of every employee's salary
+ * db.select({ value: sum(employees.salary) }).from(employees)
+ * ```
+ *
+ * @see sumDistinct to get the sum of all non-null and non-duplicate values in `expression`
+ */
+export function sum(expression: SQLWrapper): SQL<string | null> {
+	return sql`sum(${expression})`.mapWith(String);
+}
+
+/**
+ * Returns the sum of all non-null and non-duplicate values in `expression`.
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // Sum of every employee's salary where `salary` is distinct (no duplicates)
+ * db.select({ value: sumDistinct(employees.salary) }).from(employees)
+ * ```
+ *
+ * @see sum to get the sum of all non-null values in `expression`, including duplicates
+ */
+export function sumDistinct(expression: SQLWrapper): SQL<string | null> {
+	return sql`sum(distinct ${expression})`.mapWith(String);
+}
+
+/**
+ * Returns the maximum value in `expression`.
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // The employee with the highest salary
+ * db.select({ value: max(employees.salary) }).from(employees)
+ * ```
+ */
+export function max<T extends SQLWrapper>(expression: T): SQL<(T extends AnyColumn ? T['_']['data'] : string) | null> {
+	return sql`max(${expression})`.mapWith(is(expression, Column) ? expression : String) as any;
+}
+
+/**
+ * Returns the minimum value in `expression`.
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // The employee with the lowest salary
+ * db.select({ value: min(employees.salary) }).from(employees)
+ * ```
+ */
+export function min<T extends SQLWrapper>(expression: T): SQL<(T extends AnyColumn ? T['_']['data'] : string) | null> {
+	return sql`min(${expression})`.mapWith(is(expression, Column) ? expression : String) as any;
+}

package/src/data/query/sql/functions/index.ts

@@ -0,0 +1,2 @@
+export * from './aggregate.js';
+export * from './vector.js';

package/src/data/query/sql/functions/vector.ts

@@ -0,0 +1,178 @@
+import type { AnyColumn } from '../../column.js';
+import type { TypedQueryBuilder } from '../../query-builders/query-builder.js';
+import { type SQL, sql, type SQLWrapper } from '../sql.js';
+
+function toSql(value: number[] | string[]): string {
+	return JSON.stringify(value);
+}
+
+/**
+ * Used in sorting and in querying, if used in sorting,
+ * this specifies that the given column or expression should be sorted in an order
+ * that minimizes the L2 distance to the given value.
+ * If used in querying, this specifies that it should return the L2 distance
+ * between the given column or expression and the given value.
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // Sort cars by embedding similarity
+ * // to the given embedding
+ * db.select().from(cars)
+ *   .orderBy(l2Distance(cars.embedding, embedding));
+ * ```
+ *
+ * ```ts
+ * // Select distance of cars and embedding
+ * // to the given embedding
+ * db.select({distance: l2Distance(cars.embedding, embedding)}).from(cars)
+ * ```
+ */
+export function l2Distance(
+	column: SQLWrapper | AnyColumn,
+	value: number[] | string[] | TypedQueryBuilder<any> | string,
+): SQL {
+	if (Array.isArray(value)) {
+		return sql`${column} <-> ${toSql(value)}`;
+	}
+	return sql`${column} <-> ${value}`;
+}
+
+/**
+ * L1 distance is one of the possible distance measures between two probability distribution vectors and it is
+ * calculated as the sum of the absolute differences.
+ * The smaller the distance between the observed probability vectors, the higher the accuracy of the synthetic data
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // Sort cars by embedding similarity
+ * // to the given embedding
+ * db.select().from(cars)
+ *   .orderBy(l1Distance(cars.embedding, embedding));
+ * ```
+ *
+ * ```ts
+ * // Select distance of cars and embedding
+ * // to the given embedding
+ * db.select({distance: l1Distance(cars.embedding, embedding)}).from(cars)
+ * ```
+ */
+export function l1Distance(
+	column: SQLWrapper | AnyColumn,
+	value: number[] | string[] | TypedQueryBuilder<any> | string,
+): SQL {
+	if (Array.isArray(value)) {
+		return sql`${column} <+> ${toSql(value)}`;
+	}
+	return sql`${column} <+> ${value}`;
+}
+
+/**
+ * Used in sorting and in querying, if used in sorting,
+ * this specifies that the given column or expression should be sorted in an order
+ * that minimizes the inner product distance to the given value.
+ * If used in querying, this specifies that it should return the inner product distance
+ * between the given column or expression and the given value.
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // Sort cars by embedding similarity
+ * // to the given embedding
+ * db.select().from(cars)
+ *   .orderBy(innerProduct(cars.embedding, embedding));
+ * ```
+ *
+ * ```ts
+ * // Select distance of cars and embedding
+ * // to the given embedding
+ * db.select({ distance: innerProduct(cars.embedding, embedding) }).from(cars)
+ * ```
+ */
+export function innerProduct(
+	column: SQLWrapper | AnyColumn,
+	value: number[] | string[] | TypedQueryBuilder<any> | string,
+): SQL {
+	if (Array.isArray(value)) {
+		return sql`${column} <#> ${toSql(value)}`;
+	}
+	return sql`${column} <#> ${value}`;
+}
+
+/**
+ * Used in sorting and in querying, if used in sorting,
+ * this specifies that the given column or expression should be sorted in an order
+ * that minimizes the cosine distance to the given value.
+ * If used in querying, this specifies that it should return the cosine distance
+ * between the given column or expression and the given value.
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // Sort cars by embedding similarity
+ * // to the given embedding
+ * db.select().from(cars)
+ *   .orderBy(cosineDistance(cars.embedding, embedding));
+ * ```
+ *
+ * ```ts
+ * // Select distance of cars and embedding
+ * // to the given embedding
+ * db.select({distance: cosineDistance(cars.embedding, embedding)}).from(cars)
+ * ```
+ */
+export function cosineDistance(
+	column: SQLWrapper | AnyColumn,
+	value: number[] | string[] | TypedQueryBuilder<any> | string,
+): SQL {
+	if (Array.isArray(value)) {
+		return sql`${column} <=> ${toSql(value)}`;
+	}
+	return sql`${column} <=> ${value}`;
+}
+
+/**
+ * Hamming distance between two strings or vectors of equal length is the number of positions at which the
+ * corresponding symbols are different. In other words, it measures the minimum number of
+ * substitutions required to change one string into the other, or equivalently,
+ * the minimum number of errors that could have transformed one string into the other
+ *
+ * ## Examples
+ *
+ * ```ts
+ * // Sort cars by embedding similarity
+ * // to the given embedding
+ * db.select().from(cars)
+ *   .orderBy(hammingDistance(cars.embedding, embedding));
+ * ```
+ */
+export function hammingDistance(
+	column: SQLWrapper | AnyColumn,
+	value: number[] | string[] | TypedQueryBuilder<any> | string,
+): SQL {
+	if (Array.isArray(value)) {
+		return sql`${column} <~> ${toSql(value)}`;
+	}
+	return sql`${column} <~> ${value}`;
+}
+
+/**
+ * ## Examples
+ *
+ * ```ts
+ * // Sort cars by embedding similarity
+ * // to the given embedding
+ * db.select().from(cars)
+ *   .orderBy(jaccardDistance(cars.embedding, embedding));
+ * ```
+ */
+export function jaccardDistance(
+	column: SQLWrapper | AnyColumn,
+	value: number[] | string[] | TypedQueryBuilder<any> | string,
+): SQL {
+	if (Array.isArray(value)) {
+		return sql`${column} <%> ${toSql(value)}`;
+	}
+	return sql`${column} <%> ${value}`;
+}

package/src/data/query/sql/index.ts

@@ -0,0 +1,3 @@
+export * from './expressions/index.js';
+export * from './functions/index.js';
+export * from './sql.js';