diff --git a/src/Postgres/Library.fs b/src/Postgres/Library.fs index 441117b..d0ab978 100644 --- a/src/Postgres/Library.fs +++ b/src/Postgres/Library.fs @@ -3,10 +3,10 @@ /// The type of index to generate for the document [] type DocumentIndex = - + /// A GIN index with standard operations (all operators supported) | Full - + /// /// A GIN index with JSONPath operations (optimized for @>, @?, @@ operators) /// @@ -27,7 +27,7 @@ module Configuration = let useDataSource source = if Option.isSome dataSourceValue then dataSourceValue.Value.Dispose() dataSourceValue <- Some source - + /// Retrieve the currently configured data source /// The current data source /// If no data source has been configured @@ -36,14 +36,14 @@ module Configuration = match dataSourceValue with | Some source -> source | None -> invalidOp "Please provide a data source before attempting data access" - + open Npgsql.FSharp /// Helper functions [] module private Helpers = - + /// Shorthand to retrieve the data source as SqlProps let internal fromDataSource () = Configuration.dataSource () |> Sql.fromDataSource @@ -53,7 +53,7 @@ module private Helpers = let! _ = it () } - + /// Create a number or string parameter, or use the given parameter derivation function if non-(numeric or string) let internal parameterFor<'T> (value: 'T) (catchAllFunc: 'T -> SqlValue) = match box value with @@ -77,7 +77,7 @@ open BitBadger.Documents /// Functions for creating parameters [] module Parameters = - + /// Create an ID parameter (name "@id") /// The key value for the ID parameter /// The name and parameter value for the ID @@ -92,7 +92,7 @@ module Parameters = [] let jsonParam (name: string) (it: 'TJson) = name, Sql.jsonb (Configuration.serializer().Serialize it) - + /// Create JSON field parameters /// The Fields to convert to parameters /// The current parameters for the query @@ -114,7 +114,7 @@ module Parameters = yield! values |> Seq.mapi (fun idx v -> - let paramName = $"{p}_{idx}" + let paramName = $"{p}_{idx}" paramName, Sql.parameter (NpgsqlParameter(paramName, v))) | InArray (_, values) -> let p = name.Derive it.ParameterName @@ -134,17 +134,17 @@ module Parameters = let fieldNameParams (fieldNames: string seq) = if Seq.length fieldNames = 1 then "@name", Sql.string (Seq.head fieldNames) else "@name", Sql.stringArray (Array.ofSeq fieldNames) - + /// An empty parameter sequence [] let noParams = Seq.empty - + /// Query construction functions [] module Query = - + /// /// Create a WHERE clause fragment to implement a comparison on fields in a JSON document /// @@ -185,17 +185,17 @@ module Query = [] let whereById<'TKey> (docId: 'TKey) = whereByFields Any [ { Field.Equal (Configuration.idField ()) docId with ParameterName = Some "@id" } ] - + /// Table and index definition queries module Definition = - + /// SQL statement to create a document table /// The name of the table (may include schema) /// A query to create the table if it does not exist [] let ensureTable name = Query.Definition.ensureTableFor name "JSONB" - + /// SQL statement to create an index on JSON documents in the specified table /// The name of the table to be indexed (may include schema) /// The type of document index to create @@ -214,152 +214,225 @@ module Query = [] let whereDataContains paramName = $"data @> %s{paramName}" - - /// Create a WHERE clause fragment to implement a @? (JSON Path match) condition + + /// + /// Create a WHERE clause fragment to implement a @? (JSON Path match) condition + /// + /// The parameter name for the query + /// A WHERE clause fragment for the JSON Path match condition [] let whereJsonPathMatches paramName = $"data @? %s{paramName}::jsonpath" - - /// Create an UPDATE statement to patch documents + + /// Create an UPDATE statement to patch documents + /// The table to be updated + /// A query to patch documents [] let patch tableName = $"UPDATE %s{tableName} SET data = data || @data" - /// Create an UPDATE statement to remove fields from documents + /// Create an UPDATE statement to remove fields from documents + /// The table to be updated + /// A query to remove fields from documents [] let removeFields tableName = $"UPDATE %s{tableName} SET data = data - @name" - /// Create a query by a document's ID + /// Create a query by a document's ID + /// The SQL statement to be run against a document by its ID + /// The ID of the document targeted + /// A query addressing a document by its ID [] let byId<'TKey> statement (docId: 'TKey) = Query.statementWhere statement (whereById docId) - - /// Create a query on JSON fields + + /// Create a query on JSON fields + /// The SQL statement to be run against matching fields + /// Whether to match any or all of the field conditions + /// The field conditions to be matched + /// A query addressing documents by field matching conditions [] let byFields statement howMatched fields = Query.statementWhere statement (whereByFields howMatched fields) - - /// Create a JSON containment query + + /// Create a JSON containment query + /// The SQL statement to be run against the containment query + /// A query addressing documents by a JSON containment query [] let byContains statement = Query.statementWhere statement (whereDataContains "@criteria") - - /// Create a JSON Path match query + + /// Create a JSON Path match query + /// The SQL statement to run against the JSON Path match + /// A query addressing documents by a JSON Path match [] let byPathMatch statement = Query.statementWhere statement (whereJsonPathMatches "@path") -/// Functions for dealing with results +/// Functions for dealing with results [] module Results = - - /// Create a domain item from a document, specifying the field in which the document is found + + /// Create a domain item from a document, specifying the field in which the document is found + /// The field name containing the JSON document + /// A row reader set to the row with the document to be constructed + /// The constructed domain item [] let fromDocument<'T> field (row: RowReader) : 'T = Configuration.serializer().Deserialize<'T>(row.string field) - - /// Create a domain item from a document + + /// Create a domain item from a document + /// A row reader set to the row with the document to be constructed + /// The constructed domain item [] let fromData<'T> row : 'T = fromDocument "data" row - - /// Extract a count from the column "it" + + /// Extract a count from the column it + /// A row reader set to the row with the count to retrieve + /// The count from the row [] let toCount (row: RowReader) = row.int "it" - - /// Extract a true/false value from the column "it" + + /// Extract a true/false value from the column it + /// A row reader set to the row with the true/false value to retrieve + /// The true/false value from the row [] let toExists (row: RowReader) = row.bool "it" -/// Versions of queries that accept SqlProps as the last parameter +/// Versions of queries that accept SqlProps as the last parameter module WithProps = - + module FSharpList = Microsoft.FSharp.Collections.List - - /// Commands to execute custom SQL queries + + /// Commands to execute custom SQL queries [] module Custom = - /// Execute a query that returns a list of results + /// Execute a query that returns a list of results + /// The query to retrieve the results + /// Parameters to use for the query + /// The mapping function between the document and the domain item + /// The SqlProps to use to execute the query + /// A list of results for the given query [] let list<'TDoc> query parameters (mapFunc: RowReader -> 'TDoc) sqlProps = Sql.query query sqlProps |> Sql.parameters (List.ofSeq parameters) |> Sql.executeAsync mapFunc - /// Execute a query that returns a list of results + /// Execute a query that returns a list of results + /// The query to retrieve the results + /// Parameters to use for the query + /// The mapping function between the document and the domain item + /// The SqlProps to use to execute the query + /// A list of results for the given query let List<'TDoc>(query, parameters, mapFunc: System.Func, sqlProps) = backgroundTask { let! results = list<'TDoc> query parameters mapFunc.Invoke sqlProps return ResizeArray results } - - /// Execute a query that returns one or no results; returns None if not found + + /// Execute a query that returns one or no results + /// The query to retrieve the results + /// Parameters to use for the query + /// The mapping function between the document and the domain item + /// The SqlProps to use to execute the query + /// Some with the first matching result, or None if not found [] let single<'TDoc> query parameters mapFunc sqlProps = backgroundTask { let! results = list<'TDoc> query parameters mapFunc sqlProps - return FSharp.Collections.List.tryHead results + return FSharpList.tryHead results } - /// Execute a query that returns one or no results; returns null if not found + /// Execute a query that returns one or no results + /// The query to retrieve the results + /// Parameters to use for the query + /// The mapping function between the document and the domain item + /// The SqlProps to use to execute the query + /// The first matching result, or null if not found let Single<'TDoc when 'TDoc: null and 'TDoc: not struct>( query, parameters, mapFunc: System.Func, sqlProps) = backgroundTask { let! result = single<'TDoc> query parameters mapFunc.Invoke sqlProps return Option.toObj result } - /// Execute a query that returns no results + /// Execute a query that returns no results + /// The query to retrieve the results + /// Parameters to use for the query + /// The SqlProps to use to execute the query [] let nonQuery query parameters sqlProps = Sql.query query sqlProps |> Sql.parameters (FSharpList.ofSeq parameters) |> Sql.executeNonQueryAsync |> ignoreTask - - /// Execute a query that returns a scalar value + + /// Execute a query that returns a scalar value + /// The query to retrieve the value + /// Parameters to use for the query + /// The mapping function to obtain the value + /// The SqlProps to use to execute the query + /// The scalar value for the query [] let scalar<'T when 'T: struct> query parameters (mapFunc: RowReader -> 'T) sqlProps = Sql.query query sqlProps |> Sql.parameters (FSharpList.ofSeq parameters) |> Sql.executeRowAsync mapFunc - - /// Execute a query that returns a scalar value + + /// Execute a query that returns a scalar value + /// The query to retrieve the value + /// Parameters to use for the query + /// The mapping function to obtain the value + /// The SqlProps to use to execute the query + /// The scalar value for the query let Scalar<'T when 'T: struct>(query, parameters, mapFunc: System.Func, sqlProps) = scalar<'T> query parameters mapFunc.Invoke sqlProps - /// Table and index definition commands + /// Table and index definition commands module Definition = - - /// Create a document table + + /// Create a document table + /// The table whose existence should be ensured (may include schema) + /// The SqlProps to use to execute the query [] let ensureTable name sqlProps = backgroundTask { do! Custom.nonQuery (Query.Definition.ensureTable name) [] sqlProps do! Custom.nonQuery (Query.Definition.ensureKey name PostgreSQL) [] sqlProps } - /// Create an index on documents in the specified table + /// Create an index on documents in the specified table + /// The table to be indexed (may include schema) + /// The type of document index to create + /// The SqlProps to use to execute the query [] let ensureDocumentIndex name idxType sqlProps = Custom.nonQuery (Query.Definition.ensureDocumentIndex name idxType) [] sqlProps - - /// Create an index on field(s) within documents in the specified table + + /// Create an index on field(s) within documents in the specified table + /// The table to be indexed (may include schema) + /// The name of the index to create + /// One or more fields to be indexed + /// The SqlProps to use to execute the query [] let ensureFieldIndex tableName indexName fields sqlProps = Custom.nonQuery (Query.Definition.ensureIndexOn tableName indexName fields PostgreSQL) [] sqlProps - /// Commands to add documents + /// Commands to add documents [] module Document = - - /// Insert a new document + + /// Insert a new document + /// The table into which the document should be inserted (may include schema) + /// The document to be inserted + /// The SqlProps to use to execute the query [] let insert<'TDoc> tableName (document: 'TDoc) sqlProps = let query = - match Configuration.autoIdStrategy () with + match Configuration.autoIdStrategy () with | Disabled -> Query.insert tableName | strategy -> let idField = Configuration.idField () @@ -376,48 +449,78 @@ module WithProps = (Query.insert tableName).Replace("@data", dataParam) Custom.nonQuery query [ jsonParam "@data" document ] sqlProps + /// /// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert") + /// + /// The table into which the document should be saved (may include schema) + /// The document to be saved + /// The SqlProps to use to execute the query [] let save<'TDoc> tableName (document: 'TDoc) sqlProps = Custom.nonQuery (Query.save tableName) [ jsonParam "@data" document ] sqlProps - /// Commands to count documents + /// Commands to count documents [] module Count = - - /// Count all documents in a table + + /// Count all documents in a table + /// The table in which documents should be counted (may include schema) + /// The SqlProps to use to execute the query + /// The count of the documents in the table [] let all tableName sqlProps = Custom.scalar (Query.count tableName) [] toCount sqlProps - - /// Count matching documents using JSON field comparisons (->> =) + + /// Count matching documents using JSON field comparisons (->> =, etc.) + /// The table in which documents should be counted (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The SqlProps to use to execute the query + /// The count of matching documents in the table [] let byFields tableName howMatched fields sqlProps = Custom.scalar (Query.byFields (Query.count tableName) howMatched fields) (addFieldParams fields []) toCount sqlProps - - /// Count matching documents using a JSON containment query (@>) + + /// Count matching documents using a JSON containment query (@>) + /// The table in which documents should be counted (may include schema) + /// The document to match with the containment query + /// The SqlProps to use to execute the query + /// The count of the documents in the table [] let byContains tableName (criteria: 'TContains) sqlProps = Custom.scalar (Query.byContains (Query.count tableName)) [ jsonParam "@criteria" criteria ] toCount sqlProps - /// Count matching documents using a JSON Path match query (@?) + /// Count matching documents using a JSON Path match query (@?) + /// The table in which documents should be counted (may include schema) + /// The JSON Path expression to be matched + /// The SqlProps to use to execute the query + /// The count of the documents in the table [] let byJsonPath tableName jsonPath sqlProps = Custom.scalar (Query.byPathMatch (Query.count tableName)) [ "@path", Sql.string jsonPath ] toCount sqlProps - - /// Commands to determine if documents exist + + /// Commands to determine if documents exist [] module Exists = - /// Determine if a document exists for the given ID + /// Determine if a document exists for the given ID + /// The table in which existence should be checked (may include schema) + /// The ID of the document whose existence should be checked + /// The SqlProps to use to execute the query + /// True if a document exists, false if not [] let byId tableName (docId: 'TKey) sqlProps = Custom.scalar (Query.exists tableName (Query.whereById docId)) [ idParam docId ] toExists sqlProps - /// Determine if a document exists using JSON field comparisons (->> =) + /// Determine if a document exists using JSON field comparisons (->> =, etc.) + /// The table in which existence should be checked (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The SqlProps to use to execute the query + /// True if any matching documents exist, false if not [] let byFields tableName howMatched fields sqlProps = Custom.scalar @@ -425,8 +528,12 @@ module WithProps = (addFieldParams fields []) toExists sqlProps - - /// Determine if a document exists using a JSON containment query (@>) + + /// Determine if a document exists using a JSON containment query (@>) + /// The table in which existence should be checked (may include schema) + /// The document to match with the containment query + /// The SqlProps to use to execute the query + /// True if any matching documents exist, false if not [] let byContains tableName (criteria: 'TContains) sqlProps = Custom.scalar @@ -435,7 +542,11 @@ module WithProps = toExists sqlProps - /// Determine if a document exists using a JSON Path match query (@?) + /// Determine if a document exists using a JSON Path match query (@?) + /// The table in which existence should be checked (may include schema) + /// The JSON Path expression to be matched + /// The SqlProps to use to execute the query + /// True if any matching documents exist, false if not [] let byJsonPath tableName jsonPath sqlProps = Custom.scalar @@ -444,40 +555,67 @@ module WithProps = toExists sqlProps - /// Commands to determine if documents exist + /// Commands to determine if documents exist [] module Find = - - /// Retrieve all documents in the given table + + /// Retrieve all documents in the given table + /// The table from which documents should be retrieved (may include schema) + /// The SqlProps to use to execute the query + /// All documents from the given table [] let all<'TDoc> tableName sqlProps = Custom.list<'TDoc> (Query.find tableName) [] fromData<'TDoc> sqlProps - /// Retrieve all documents in the given table + /// Retrieve all documents in the given table + /// The table from which documents should be retrieved (may include schema) + /// The SqlProps to use to execute the query + /// All documents from the given table let All<'TDoc>(tableName, sqlProps) = Custom.List<'TDoc>(Query.find tableName, [], fromData<'TDoc>, sqlProps) - /// Retrieve all documents in the given table ordered by the given fields in the document + /// Retrieve all documents in the given table ordered by the given fields in the document + /// The table from which documents should be retrieved (may include schema) + /// Fields by which the results should be ordered + /// The SqlProps to use to execute the query + /// All documents from the given table, ordered by the given fields [] let allOrdered<'TDoc> tableName orderFields sqlProps = Custom.list<'TDoc> (Query.find tableName + Query.orderBy orderFields PostgreSQL) [] fromData<'TDoc> sqlProps - /// Retrieve all documents in the given table ordered by the given fields in the document + /// Retrieve all documents in the given table ordered by the given fields in the document + /// The table from which documents should be retrieved (may include schema) + /// Fields by which the results should be ordered + /// The SqlProps to use to execute the query + /// All documents from the given table, ordered by the given fields let AllOrdered<'TDoc>(tableName, orderFields, sqlProps) = Custom.List<'TDoc>( Query.find tableName + Query.orderBy orderFields PostgreSQL, [], fromData<'TDoc>, sqlProps) - /// Retrieve a document by its ID (returns None if not found) + /// Retrieve a document by its ID + /// The table from which a document should be retrieved (may include schema) + /// The ID of the document to retrieve + /// The SqlProps to use to execute the query + /// Some with the document if found, None otherwise [] let byId<'TKey, 'TDoc> tableName (docId: 'TKey) sqlProps = Custom.single (Query.byId (Query.find tableName) docId) [ idParam docId ] fromData<'TDoc> sqlProps - /// Retrieve a document by its ID (returns null if not found) + /// Retrieve a document by its ID + /// The table from which a document should be retrieved (may include schema) + /// The ID of the document to retrieve + /// The SqlProps to use to execute the query + /// The document if found, null otherwise let ById<'TKey, 'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, docId: 'TKey, sqlProps) = Custom.Single<'TDoc>( Query.byId (Query.find tableName) docId, [ idParam docId ], fromData<'TDoc>, sqlProps) - /// Retrieve documents matching JSON field comparisons (->> =) + /// Retrieve documents matching JSON field comparisons (->> =, etc.) + /// The table from which documents should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The SqlProps to use to execute the query + /// All documents matching the given fields [] let byFields<'TDoc> tableName howMatched fields sqlProps = Custom.list<'TDoc> @@ -485,16 +623,30 @@ module WithProps = (addFieldParams fields []) fromData<'TDoc> sqlProps - - /// Retrieve documents matching JSON field comparisons (->> =) + + /// Retrieve documents matching JSON field comparisons (->> =, etc.) + /// The table from which documents should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The SqlProps to use to execute the query + /// All documents matching the given fields let ByFields<'TDoc>(tableName, howMatched, fields, sqlProps) = Custom.List<'TDoc>( Query.byFields (Query.find tableName) howMatched fields, addFieldParams fields [], fromData<'TDoc>, sqlProps) - - /// Retrieve documents matching JSON field comparisons (->> =) ordered by the given fields in the document + + /// + /// Retrieve documents matching JSON field comparisons (->> =, etc.) ordered by the given fields + /// in the document + /// + /// The table from which documents should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// Fields by which the results should be ordered + /// The SqlProps to use to execute the query + /// All documents matching the given fields, ordered by the other given fields [] let byFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields sqlProps = Custom.list<'TDoc> @@ -502,22 +654,39 @@ module WithProps = (addFieldParams queryFields []) fromData<'TDoc> sqlProps - - /// Retrieve documents matching JSON field comparisons (->> =) ordered by the given fields in the document + + /// + /// Retrieve documents matching JSON field comparisons (->> =, etc.) ordered by the given fields + /// in the document + /// + /// The table from which documents should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// Fields by which the results should be ordered + /// The SqlProps to use to execute the query + /// All documents matching the given fields, ordered by the other given fields let ByFieldsOrdered<'TDoc>(tableName, howMatched, queryFields, orderFields, sqlProps) = Custom.List<'TDoc>( Query.byFields (Query.find tableName) howMatched queryFields + Query.orderBy orderFields PostgreSQL, addFieldParams queryFields [], fromData<'TDoc>, sqlProps) - - /// Retrieve documents matching a JSON containment query (@>) + + /// Retrieve documents matching a JSON containment query (@>) + /// The table from which documents should be retrieved (may include schema) + /// The document to match with the containment query + /// The SqlProps to use to execute the query + /// All documents matching the given containment query [] let byContains<'TDoc> tableName (criteria: obj) sqlProps = Custom.list<'TDoc> (Query.byContains (Query.find tableName)) [ jsonParam "@criteria" criteria ] fromData<'TDoc> sqlProps - /// Retrieve documents matching a JSON containment query (@>) + /// Retrieve documents matching a JSON containment query (@>) + /// The table from which documents should be retrieved (may include schema) + /// The document to match with the containment query + /// The SqlProps to use to execute the query + /// All documents matching the given containment query let ByContains<'TDoc>(tableName, criteria: obj, sqlProps) = Custom.List<'TDoc>( Query.byContains (Query.find tableName), @@ -525,7 +694,15 @@ module WithProps = fromData<'TDoc>, sqlProps) - /// Retrieve documents matching a JSON containment query (@>) ordered by the given fields in the document + /// + /// Retrieve documents matching a JSON containment query (@>) ordered by the given fields in the + /// document + /// + /// The table from which documents should be retrieved (may include schema) + /// The document to match with the containment query + /// Fields by which the results should be ordered + /// The SqlProps to use to execute the query + /// All documents matching the given containment query, ordered by the given fields [] let byContainsOrdered<'TDoc> tableName (criteria: obj) orderFields sqlProps = Custom.list<'TDoc> @@ -534,7 +711,15 @@ module WithProps = fromData<'TDoc> sqlProps - /// Retrieve documents matching a JSON containment query (@>) ordered by the given fields in the document + /// + /// Retrieve documents matching a JSON containment query (@>) ordered by the given fields in the + /// document + /// + /// The table from which documents should be retrieved (may include schema) + /// The document to match with the containment query + /// Fields by which the results should be ordered + /// The SqlProps to use to execute the query + /// All documents matching the given containment query, ordered by the given fields let ByContainsOrdered<'TDoc>(tableName, criteria: obj, orderFields, sqlProps) = Custom.List<'TDoc>( Query.byContains (Query.find tableName) + Query.orderBy orderFields PostgreSQL, @@ -542,21 +727,37 @@ module WithProps = fromData<'TDoc>, sqlProps) - /// Retrieve documents matching a JSON Path match query (@?) + /// Retrieve documents matching a JSON Path match query (@?) + /// The table from which documents should be retrieved (may include schema) + /// The JSON Path expression to match + /// The SqlProps to use to execute the query + /// All documents matching the given JSON Path expression [] let byJsonPath<'TDoc> tableName jsonPath sqlProps = Custom.list<'TDoc> (Query.byPathMatch (Query.find tableName)) [ "@path", Sql.string jsonPath ] fromData<'TDoc> sqlProps - - /// Retrieve documents matching a JSON Path match query (@?) + + /// Retrieve documents matching a JSON Path match query (@?) + /// The table from which documents should be retrieved (may include schema) + /// The JSON Path expression to match + /// The SqlProps to use to execute the query + /// All documents matching the given JSON Path expression let ByJsonPath<'TDoc>(tableName, jsonPath, sqlProps) = Custom.List<'TDoc>( Query.byPathMatch (Query.find tableName), [ "@path", Sql.string jsonPath ], fromData<'TDoc>, sqlProps) - - /// Retrieve documents matching a JSON Path match query (@?) ordered by the given fields in the document + + /// + /// Retrieve documents matching a JSON Path match query (@?) ordered by the given fields in the + /// document + /// + /// The table from which documents should be retrieved (may include schema) + /// The JSON Path expression to match + /// Fields by which the results should be ordered + /// The SqlProps to use to execute the query + /// All documents matching the given JSON Path expression, ordered by the given fields [] let byJsonPathOrdered<'TDoc> tableName jsonPath orderFields sqlProps = Custom.list<'TDoc> @@ -564,16 +765,29 @@ module WithProps = [ "@path", Sql.string jsonPath ] fromData<'TDoc> sqlProps - - /// Retrieve documents matching a JSON Path match query (@?) ordered by the given fields in the document + + /// + /// Retrieve documents matching a JSON Path match query (@?) ordered by the given fields in the + /// document + /// + /// The table from which documents should be retrieved (may include schema) + /// The JSON Path expression to match + /// Fields by which the results should be ordered + /// The SqlProps to use to execute the query + /// All documents matching the given JSON Path expression, ordered by the given fields let ByJsonPathOrdered<'TDoc>(tableName, jsonPath, orderFields, sqlProps) = Custom.List<'TDoc>( Query.byPathMatch (Query.find tableName) + Query.orderBy orderFields PostgreSQL, [ "@path", Sql.string jsonPath ], fromData<'TDoc>, sqlProps) - - /// Retrieve the first document matching JSON field comparisons (->> =); returns None if not found + + /// Retrieve the first document matching JSON field comparisons (->> =, etc.) + /// The table from which a document should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The SqlProps to use to execute the query + /// Some with the first document, or None if not found [] let firstByFields<'TDoc> tableName howMatched fields sqlProps = Custom.single<'TDoc> @@ -581,17 +795,32 @@ module WithProps = (addFieldParams fields []) fromData<'TDoc> sqlProps - - /// Retrieve the first document matching JSON field comparisons (->> =); returns null if not found + + /// Retrieve the first document matching JSON field comparisons (->> =, etc.) + /// The table from which a document should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The SqlProps to use to execute the query + /// The first document, or null if not found let FirstByFields<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, howMatched, fields, sqlProps) = Custom.Single<'TDoc>( $"{Query.byFields (Query.find tableName) howMatched fields} LIMIT 1", addFieldParams fields [], fromData<'TDoc>, sqlProps) - - /// Retrieve the first document matching JSON field comparisons (->> =) ordered by the given fields in the - /// document; returns None if not found + + /// + /// Retrieve the first document matching JSON field comparisons (->> =, etc.) ordered by the + /// given fields in the document + /// + /// The table from which a document should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// Fields by which the results should be ordered + /// The SqlProps to use to execute the query + /// + /// Some with the first document ordered by the given fields, or None if not found + /// [] let firstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields sqlProps = Custom.single<'TDoc> @@ -599,9 +828,17 @@ module WithProps = (addFieldParams queryFields []) fromData<'TDoc> sqlProps - - /// Retrieve the first document matching JSON field comparisons (->> =) ordered by the given fields in the - /// document; returns null if not found + + /// + /// Retrieve the first document matching JSON field comparisons (->> =, etc.) ordered by the + /// given fields in the document + /// + /// The table from which a document should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// Fields by which the results should be ordered + /// The SqlProps to use to execute the query + /// The first document ordered by the given fields, or null if not found let FirstByFieldsOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>( tableName, howMatched, queryFields, orderFields, sqlProps) = Custom.Single<'TDoc>( @@ -609,8 +846,12 @@ module WithProps = addFieldParams queryFields [], fromData<'TDoc>, sqlProps) - - /// Retrieve the first document matching a JSON containment query (@>); returns None if not found + + /// Retrieve the first document matching a JSON containment query (@>) + /// The table from which a document should be retrieved (may include schema) + /// The document to match with the containment query + /// The SqlProps to use to execute the query + /// Some with the first document, or None if not found [] let firstByContains<'TDoc> tableName (criteria: obj) sqlProps = Custom.single<'TDoc> @@ -619,7 +860,11 @@ module WithProps = fromData<'TDoc> sqlProps - /// Retrieve the first document matching a JSON containment query (@>); returns null if not found + /// Retrieve the first document matching a JSON containment query (@>) + /// The table from which a document should be retrieved (may include schema) + /// The document to match with the containment query + /// The SqlProps to use to execute the query + /// The first document, or null if not found let FirstByContains<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, criteria: obj, sqlProps) = Custom.Single<'TDoc>( $"{Query.byContains (Query.find tableName)} LIMIT 1", @@ -627,8 +872,17 @@ module WithProps = fromData<'TDoc>, sqlProps) - /// Retrieve the first document matching a JSON containment query (@>) ordered by the given fields in the - /// document; returns None if not found + /// + /// Retrieve the first document matching a JSON containment query (@>) ordered by the given fields + /// in the document + /// + /// The table from which a document should be retrieved (may include schema) + /// The document to match with the containment query + /// Fields by which the results should be ordered + /// The SqlProps to use to execute the query + /// + /// Some with the first document ordered by the given fields, or None if not found + /// [] let firstByContainsOrdered<'TDoc> tableName (criteria: obj) orderFields sqlProps = Custom.single<'TDoc> @@ -637,8 +891,15 @@ module WithProps = fromData<'TDoc> sqlProps - /// Retrieve the first document matching a JSON containment query (@>) ordered by the given fields in the - /// document; returns null if not found + /// + /// Retrieve the first document matching a JSON containment query (@>) ordered by the given fields + /// in the document + /// + /// The table from which a document should be retrieved (may include schema) + /// The document to match with the containment query + /// Fields by which the results should be ordered + /// The SqlProps to use to execute the query + /// The first document ordered by the given fields, or null if not found let FirstByContainsOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>( tableName, criteria: obj, orderFields, sqlProps) = Custom.Single<'TDoc>( @@ -647,7 +908,11 @@ module WithProps = fromData<'TDoc>, sqlProps) - /// Retrieve the first document matching a JSON Path match query (@?); returns None if not found + /// Retrieve the first document matching a JSON Path match query (@?) + /// The table from which a document should be retrieved (may include schema) + /// The JSON Path expression to match + /// The SqlProps to use to execute the query + /// Some with the first document, or None if not found [] let firstByJsonPath<'TDoc> tableName jsonPath sqlProps = Custom.single<'TDoc> @@ -656,7 +921,11 @@ module WithProps = fromData<'TDoc> sqlProps - /// Retrieve the first document matching a JSON Path match query (@?); returns null if not found + /// Retrieve the first document matching a JSON Path match query (@?) + /// The table from which a document should be retrieved (may include schema) + /// The JSON Path expression to match + /// The SqlProps to use to execute the query + /// The first document, or null if not found let FirstByJsonPath<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, jsonPath, sqlProps) = Custom.Single<'TDoc>( $"{Query.byPathMatch (Query.find tableName)} LIMIT 1", @@ -664,8 +933,17 @@ module WithProps = fromData<'TDoc>, sqlProps) - /// Retrieve the first document matching a JSON Path match query (@?) ordered by the given fields in the - /// document; returns None if not found + /// + /// Retrieve the first document matching a JSON Path match query (@?) ordered by the given fields in + /// the document + /// + /// The table from which a document should be retrieved (may include schema) + /// The JSON Path expression to match + /// Fields by which the results should be ordered + /// The SqlProps to use to execute the query + /// + /// Some with the first document ordered by the given fields, or None if not found + /// [] let firstByJsonPathOrdered<'TDoc> tableName jsonPath orderFields sqlProps = Custom.single<'TDoc> @@ -674,8 +952,15 @@ module WithProps = fromData<'TDoc> sqlProps - /// Retrieve the first document matching a JSON Path match query (@?) ordered by the given fields in the - /// document; returns null if not found + /// + /// Retrieve the first document matching a JSON Path match query (@?) ordered by the given fields in + /// the document + /// + /// The table from which a document should be retrieved (may include schema) + /// The JSON Path expression to match + /// Fields by which the results should be ordered + /// The SqlProps to use to execute the query + /// The first document ordered by the given fields, or null if not found let FirstByJsonPathOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>( tableName, jsonPath, orderFields, sqlProps) = Custom.Single<'TDoc>( @@ -684,52 +969,90 @@ module WithProps = fromData<'TDoc>, sqlProps) - /// Commands to update documents + /// Commands to update documents [] module Update = - - /// Update an entire document by its ID + + /// Update (replace) an entire document by its ID + /// The table in which a document should be updated (may include schema) + /// The ID of the document to be updated (replaced) + /// The new document + /// The SqlProps to use to execute the query [] let byId tableName (docId: 'TKey) (document: 'TDoc) sqlProps = Custom.nonQuery (Query.byId (Query.update tableName) docId) [ idParam docId; jsonParam "@data" document ] sqlProps - - /// Update an entire document by its ID, using the provided function to obtain the ID from the document + + /// + /// Update (replace) an entire document by its ID, using the provided function to obtain the ID from the + /// document + /// + /// The table in which a document should be updated (may include schema) + /// The function to obtain the ID of the document + /// The new document + /// The SqlProps to use to execute the query [] let byFunc tableName (idFunc: 'TDoc -> 'TKey) (document: 'TDoc) sqlProps = byId tableName (idFunc document) document sqlProps - - /// Update an entire document by its ID, using the provided function to obtain the ID from the document + + /// + /// Update (replace) an entire document by its ID, using the provided function to obtain the ID from the + /// document + /// + /// The table in which a document should be updated (may include schema) + /// The function to obtain the ID of the document + /// The new document + /// The SqlProps to use to execute the query let ByFunc(tableName, idFunc: System.Func<'TDoc, 'TKey>, document: 'TDoc, sqlProps) = byFunc tableName idFunc.Invoke document sqlProps - /// Commands to patch (partially update) documents + /// Commands to patch (partially update) documents [] module Patch = - - /// Patch a document by its ID + + /// Patch a document by its ID + /// The table in which a document should be patched (may include schema) + /// The ID of the document to patch + /// The partial document to patch the existing document + /// The SqlProps to use to execute the query [] let byId tableName (docId: 'TKey) (patch: 'TPatch) sqlProps = Custom.nonQuery (Query.byId (Query.patch tableName) docId) [ idParam docId; jsonParam "@data" patch ] sqlProps - - /// Patch documents using a JSON field comparison query in the WHERE clause (->> =) + + /// + /// Patch documents using a JSON field comparison query in the WHERE clause (->> =, + /// etc.) + /// + /// The table in which documents should be patched (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The partial document to patch the existing document + /// The SqlProps to use to execute the query [] let byFields tableName howMatched fields (patch: 'TPatch) sqlProps = Custom.nonQuery (Query.byFields (Query.patch tableName) howMatched fields) (addFieldParams fields [ jsonParam "@data" patch ]) sqlProps - - /// Patch documents using a JSON containment query in the WHERE clause (@>) + + /// Patch documents using a JSON containment query in the WHERE clause (@>) + /// The table in which documents should be patched (may include schema) + /// The document to match the containment query + /// The partial document to patch the existing document + /// The SqlProps to use to execute the query [] let byContains tableName (criteria: 'TContains) (patch: 'TPatch) sqlProps = Custom.nonQuery (Query.byContains (Query.patch tableName)) [ jsonParam "@data" patch; jsonParam "@criteria" criteria ] sqlProps - - /// Patch documents using a JSON Path match query in the WHERE clause (@?) + + /// Patch documents using a JSON Path match query in the WHERE clause (@?) + /// The table in which documents should be patched (may include schema) + /// The JSON Path expression to match + /// The partial document to patch the existing document + /// The SqlProps to use to execute the query [] let byJsonPath tableName jsonPath (patch: 'TPatch) sqlProps = Custom.nonQuery @@ -737,64 +1060,94 @@ module WithProps = [ jsonParam "@data" patch; "@path", Sql.string jsonPath ] sqlProps - /// Commands to remove fields from documents + /// Commands to remove fields from documents [] module RemoveFields = - - /// Remove fields from a document by the document's ID + + /// Remove fields from a document by the document's ID + /// The table in which a document should be modified (may include schema) + /// The ID of the document to modify + /// One or more field names to remove from the document + /// The SqlProps to use to execute the query [] let byId tableName (docId: 'TKey) fieldNames sqlProps = Custom.nonQuery (Query.byId (Query.removeFields tableName) docId) [ idParam docId; fieldNameParams fieldNames ] sqlProps - - /// Remove fields from documents via a comparison on JSON fields in the document + + /// Remove fields from documents via a comparison on JSON fields in the document + /// The table in which documents should be modified (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// One or more field names to remove from the matching documents + /// The SqlProps to use to execute the query [] let byFields tableName howMatched fields fieldNames sqlProps = Custom.nonQuery (Query.byFields (Query.removeFields tableName) howMatched fields) (addFieldParams fields [ fieldNameParams fieldNames ]) sqlProps - - /// Remove fields from documents via a JSON containment query (@>) + + /// Remove fields from documents via a JSON containment query (@>) + /// The table in which documents should be modified (may include schema) + /// The document to match the containment query + /// One or more field names to remove from the matching documents + /// The SqlProps to use to execute the query [] let byContains tableName (criteria: 'TContains) fieldNames sqlProps = Custom.nonQuery (Query.byContains (Query.removeFields tableName)) [ jsonParam "@criteria" criteria; fieldNameParams fieldNames ] sqlProps - - /// Remove fields from documents via a JSON Path match query (@?) + + /// Remove fields from documents via a JSON Path match query (@?) + /// The table in which documents should be modified (may include schema) + /// The JSON Path expression to match + /// One or more field names to remove from the matching documents + /// The SqlProps to use to execute the query [] let byJsonPath tableName jsonPath fieldNames sqlProps = Custom.nonQuery (Query.byPathMatch (Query.removeFields tableName)) [ "@path", Sql.string jsonPath; fieldNameParams fieldNames ] sqlProps - - /// Commands to delete documents + + /// Commands to delete documents [] module Delete = - - /// Delete a document by its ID + + /// Delete a document by its ID + /// The table in which a document should be deleted (may include schema) + /// The ID of the document to delete + /// The SqlProps to use to execute the query [] let byId tableName (docId: 'TKey) sqlProps = Custom.nonQuery (Query.byId (Query.delete tableName) docId) [ idParam docId ] sqlProps - /// Delete documents by matching a JSON field comparison query (->> =) + /// Delete documents by matching a JSON field comparison query (->> =, etc.) + /// The table in which documents should be deleted (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The SqlProps to use to execute the query [] let byFields tableName howMatched fields sqlProps = Custom.nonQuery (Query.byFields (Query.delete tableName) howMatched fields) (addFieldParams fields []) sqlProps - - /// Delete documents by matching a JSON contains query (@>) + + /// Delete documents by matching a JSON contains query (@>) + /// The table in which documents should be deleted (may include schema) + /// The document to match the containment query + /// The SqlProps to use to execute the query [] let byContains tableName (criteria: 'TCriteria) sqlProps = Custom.nonQuery (Query.byContains (Query.delete tableName)) [ jsonParam "@criteria" criteria ] sqlProps - /// Delete documents by matching a JSON Path match query (@?) + /// Delete documents by matching a JSON Path match query (@?) + /// The table in which documents should be deleted (may include schema) + /// The JSON Path expression to match + /// The SqlProps to use to execute the query [] - let byJsonPath tableName path sqlProps = - Custom.nonQuery (Query.byPathMatch (Query.delete tableName)) [ "@path", Sql.string path ] sqlProps + let byJsonPath tableName jsonPath sqlProps = + Custom.nonQuery (Query.byPathMatch (Query.delete tableName)) [ "@path", Sql.string jsonPath ] sqlProps /// Commands to execute custom SQL queries @@ -838,7 +1191,7 @@ module Custom = /// Table and index definition commands [] module Definition = - + /// Create a document table [] let ensureTable name = @@ -848,7 +1201,7 @@ module Definition = [] let ensureDocumentIndex name idxType = WithProps.Definition.ensureDocumentIndex name idxType (fromDataSource ()) - + /// Create an index on field(s) within documents in the specified table [] let ensureFieldIndex tableName indexName fields = @@ -858,7 +1211,7 @@ module Definition = /// Document writing functions [] module Document = - + /// Insert a new document [] let insert<'TDoc> tableName (document: 'TDoc) = @@ -873,17 +1226,17 @@ module Document = /// Queries to count documents [] module Count = - + /// Count all documents in a table [] let all tableName = WithProps.Count.all tableName (fromDataSource ()) - + /// Count matching documents using a JSON field comparison query (->> =) [] let byFields tableName howMatched fields = WithProps.Count.byFields tableName howMatched fields (fromDataSource ()) - + /// Count matching documents using a JSON containment query (@>) [] let byContains tableName criteria = @@ -903,12 +1256,12 @@ module Exists = [] let byId tableName docId = WithProps.Exists.byId tableName docId (fromDataSource ()) - + /// Determine if documents exist using a JSON field comparison query (->> =) [] let byFields tableName howMatched fields = WithProps.Exists.byFields tableName howMatched fields (fromDataSource ()) - + /// Determine if documents exist using a JSON containment query (@>) [] let byContains tableName criteria = @@ -923,7 +1276,7 @@ module Exists = /// Commands to retrieve documents [] module Find = - + /// Retrieve all documents in the given table [] let all<'TDoc> tableName = @@ -955,20 +1308,20 @@ module Find = [] let byFields<'TDoc> tableName howMatched fields = WithProps.Find.byFields<'TDoc> tableName howMatched fields (fromDataSource ()) - + /// Retrieve documents matching a JSON field comparison query (->> =) let ByFields<'TDoc>(tableName, howMatched, fields) = WithProps.Find.ByFields<'TDoc>(tableName, howMatched, fields, fromDataSource ()) - + /// Retrieve documents matching a JSON field comparison query (->> =) ordered by the given fields in the document [] let byFieldsOrdered<'TDoc> tableName howMatched queryField orderFields = WithProps.Find.byFieldsOrdered<'TDoc> tableName howMatched queryField orderFields (fromDataSource ()) - + /// Retrieve documents matching a JSON field comparison query (->> =) ordered by the given fields in the document let ByFieldsOrdered<'TDoc>(tableName, howMatched, queryFields, orderFields) = WithProps.Find.ByFieldsOrdered<'TDoc>(tableName, howMatched, queryFields, orderFields, fromDataSource ()) - + /// Retrieve documents matching a JSON containment query (@>) [] let byContains<'TDoc> tableName (criteria: obj) = @@ -991,41 +1344,41 @@ module Find = [] let byJsonPath<'TDoc> tableName jsonPath = WithProps.Find.byJsonPath<'TDoc> tableName jsonPath (fromDataSource ()) - + /// Retrieve documents matching a JSON Path match query (@?) let ByJsonPath<'TDoc>(tableName, jsonPath) = WithProps.Find.ByJsonPath<'TDoc>(tableName, jsonPath, fromDataSource ()) - + /// Retrieve documents matching a JSON Path match query (@?) ordered by the given fields in the document [] let byJsonPathOrdered<'TDoc> tableName jsonPath orderFields = WithProps.Find.byJsonPathOrdered<'TDoc> tableName jsonPath orderFields (fromDataSource ()) - + /// Retrieve documents matching a JSON Path match query (@?) ordered by the given fields in the document let ByJsonPathOrdered<'TDoc>(tableName, jsonPath, orderFields) = WithProps.Find.ByJsonPathOrdered<'TDoc>(tableName, jsonPath, orderFields, fromDataSource ()) - + /// Retrieve the first document matching a JSON field comparison query (->> =); returns None if not found [] let firstByFields<'TDoc> tableName howMatched fields = WithProps.Find.firstByFields<'TDoc> tableName howMatched fields (fromDataSource ()) - + /// Retrieve the first document matching a JSON field comparison query (->> =); returns null if not found let FirstByFields<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, howMatched, fields) = WithProps.Find.FirstByFields<'TDoc>(tableName, howMatched, fields, fromDataSource ()) - + /// Retrieve the first document matching a JSON field comparison query (->> =) ordered by the given fields in the /// document; returns None if not found [] let firstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields = WithProps.Find.firstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields (fromDataSource ()) - + /// Retrieve the first document matching a JSON field comparison query (->> =) ordered by the given fields in the /// document; returns null if not found let FirstByFieldsOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>( tableName, howMatched, queryFields, orderFields) = WithProps.Find.FirstByFieldsOrdered<'TDoc>(tableName, howMatched, queryFields, orderFields, fromDataSource ()) - + /// Retrieve the first document matching a JSON containment query (@>); returns None if not found [] let firstByContains<'TDoc> tableName (criteria: obj) = @@ -1080,7 +1433,7 @@ module Update = [] let byFunc tableName (idFunc: 'TDoc -> 'TKey) (document: 'TDoc) = WithProps.Update.byFunc tableName idFunc document (fromDataSource ()) - + /// Update an entire document by its ID, using the provided function to obtain the ID from the document let ByFunc(tableName, idFunc: System.Func<'TDoc, 'TKey>, document: 'TDoc) = WithProps.Update.ByFunc(tableName, idFunc, document, fromDataSource ()) @@ -1089,22 +1442,22 @@ module Update = /// Commands to patch (partially update) documents [] module Patch = - + /// Patch a document by its ID [] let byId tableName (docId: 'TKey) (patch: 'TPatch) = WithProps.Patch.byId tableName docId patch (fromDataSource ()) - + /// Patch documents using a JSON field comparison query in the WHERE clause (->> =) [] let byFields tableName howMatched fields (patch: 'TPatch) = WithProps.Patch.byFields tableName howMatched fields patch (fromDataSource ()) - + /// Patch documents using a JSON containment query in the WHERE clause (@>) [] let byContains tableName (criteria: 'TCriteria) (patch: 'TPatch) = WithProps.Patch.byContains tableName criteria patch (fromDataSource ()) - + /// Patch documents using a JSON Path match query in the WHERE clause (@?) [] let byJsonPath tableName jsonPath (patch: 'TPatch) = @@ -1114,17 +1467,17 @@ module Patch = /// Commands to remove fields from documents [] module RemoveFields = - + /// Remove fields from a document by the document's ID [] let byId tableName (docId: 'TKey) fieldNames = WithProps.RemoveFields.byId tableName docId fieldNames (fromDataSource ()) - + /// Remove fields from documents via a comparison on JSON fields in the document [] let byFields tableName howMatched fields fieldNames = WithProps.RemoveFields.byFields tableName howMatched fields fieldNames (fromDataSource ()) - + /// Remove fields from documents via a JSON containment query (@>) [] let byContains tableName (criteria: 'TContains) fieldNames = @@ -1139,17 +1492,17 @@ module RemoveFields = /// Commands to delete documents [] module Delete = - + /// Delete a document by its ID [] let byId tableName (docId: 'TKey) = WithProps.Delete.byId tableName docId (fromDataSource ()) - + /// Delete documents by matching a JSON field comparison query (->> =) [] let byFields tableName howMatched fields = WithProps.Delete.byFields tableName howMatched fields (fromDataSource ()) - + /// Delete documents by matching a JSON containment query (@>) [] let byContains tableName (criteria: 'TContains) =