/// <summary>Versions of queries that accept <c>SqlProps</c> as the last parameter</summary>
module BitBadger.Documents.Postgres.WithProps

open BitBadger.Documents
open Npgsql.FSharp

/// <summary>Commands to execute custom SQL queries</summary>
[<RequireQualifiedAccess>]
module Custom =

    module FSharpList = Microsoft.FSharp.Collections.List

    /// <summary>Execute a query that returns a list of results</summary>
    /// <param name="query">The query to retrieve the results</param>
    /// <param name="parameters">Parameters to use for the query</param>
    /// <param name="mapFunc">The mapping function between the document and the domain item</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>A list of results for the given query</returns>
    [<CompiledName "FSharpList">]
    let list<'TDoc> query parameters (mapFunc: RowReader -> 'TDoc) sqlProps =
        Sql.query query sqlProps
        |> Sql.parameters (FSharpList.ofSeq parameters)
        |> Sql.executeAsync mapFunc

    /// <summary>Execute a query that returns a list of results</summary>
    /// <param name="query">The query to retrieve the results</param>
    /// <param name="parameters">Parameters to use for the query</param>
    /// <param name="mapFunc">The mapping function between the document and the domain item</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>A list of results for the given query</returns>
    let List<'TDoc>(query, parameters, mapFunc: System.Func<RowReader, 'TDoc>, sqlProps) = backgroundTask {
        let! results = list<'TDoc> query parameters mapFunc.Invoke sqlProps
        return ResizeArray results
    }

    /// <summary>Execute a query that returns a JSON array of results</summary>
    /// <param name="query">The query to retrieve the results</param>
    /// <param name="parameters">Parameters to use for the query</param>
    /// <param name="mapFunc">The mapping function to extract the document</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>A JSON array of results for the given query</returns>
    [<CompiledName "FSharpJsonArray">]
    let jsonArray query parameters (mapFunc: RowReader -> string) sqlProps =
        Sql.query query sqlProps
        |> Sql.parameters (FSharpList.ofSeq parameters)
        |> toJsonArray mapFunc

    /// <summary>Execute a query that returns a JSON array of results</summary>
    /// <param name="query">The query to retrieve the results</param>
    /// <param name="parameters">Parameters to use for the query</param>
    /// <param name="mapFunc">The mapping function to extract the document</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>A JSON array of results for the given query</returns>
    let JsonArray(query, parameters, mapFunc: System.Func<RowReader, string>, sqlProps) =
        jsonArray query parameters mapFunc.Invoke sqlProps

    /// <summary>Execute a query, writing its results to the given <c>PipeWriter</c></summary>
    /// <param name="query">The query to retrieve the results</param>
    /// <param name="parameters">Parameters to use for the query</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="mapFunc">The mapping function to extract the document</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "FSharpWriteJsonArray">]
    let writeJsonArray query parameters writer (mapFunc: RowReader -> string) sqlProps =
        Sql.query query sqlProps
        |> Sql.parameters (FSharpList.ofSeq parameters)
        |> writeJsonArray writer mapFunc

    /// <summary>Execute a query, writing its results to the given <c>PipeWriter</c></summary>
    /// <param name="query">The query to retrieve the results</param>
    /// <param name="parameters">Parameters to use for the query</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="mapFunc">The mapping function to extract the document</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    let WriteJsonArray(query, parameters, writer, mapFunc: System.Func<RowReader, string>, sqlProps) =
        writeJsonArray query parameters writer mapFunc.Invoke sqlProps

    /// <summary>Execute a query that returns one or no results</summary>
    /// <param name="query">The query to retrieve the results</param>
    /// <param name="parameters">Parameters to use for the query</param>
    /// <param name="mapFunc">The mapping function between the document and the domain item</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns><c>Some</c> with the first matching result, or <c>None</c> if not found</returns>
    [<CompiledName "FSharpSingle">]
    let single<'TDoc> query parameters mapFunc sqlProps = backgroundTask {
        let! results = list<'TDoc> $"{query} LIMIT 1" parameters mapFunc sqlProps
        return FSharpList.tryHead results
    }

    /// <summary>Execute a query that returns one or no results</summary>
    /// <param name="query">The query to retrieve the results</param>
    /// <param name="parameters">Parameters to use for the query</param>
    /// <param name="mapFunc">The mapping function between the document and the domain item</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The first matching result, or <c>null</c> if not found</returns>
    let Single<'TDoc when 'TDoc: null and 'TDoc: not struct>(
            query, parameters, mapFunc: System.Func<RowReader, 'TDoc>, sqlProps) = backgroundTask {
        let! result = single<'TDoc> query parameters mapFunc.Invoke sqlProps
        return Option.toObj result
    }

    /// <summary>Execute a query that returns one or no JSON documents</summary>
    /// <param name="query">The query to retrieve the results</param>
    /// <param name="parameters">Parameters to use for the query</param>
    /// <param name="mapFunc">The mapping function to extract the document</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The JSON document with the first matching result, or an empty document if not found</returns>
    [<CompiledName "FSharpJsonSingle">]
    let jsonSingle query parameters mapFunc sqlProps = backgroundTask {
        let! results = jsonArray $"%s{query} LIMIT 1" parameters mapFunc sqlProps
        return if results = "[]" then "{}" else results[1..results.Length - 2]
    }

    /// <summary>Execute a query that returns one or no JSON documents</summary>
    /// <param name="query">The query to retrieve the results</param>
    /// <param name="parameters">Parameters to use for the query</param>
    /// <param name="mapFunc">The mapping function to extract the document</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The JSON document with the first matching result, or an empty document if not found</returns>
    let JsonSingle(query, parameters, mapFunc: System.Func<RowReader, string>, sqlProps) =
        jsonSingle query parameters mapFunc.Invoke sqlProps

    /// <summary>Execute a query that returns no results</summary>
    /// <param name="query">The query to retrieve the results</param>
    /// <param name="parameters">Parameters to use for the query</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "NonQuery">]
    let nonQuery query parameters sqlProps =
        Sql.query query sqlProps
        |> Sql.parameters (FSharpList.ofSeq parameters)
        |> Sql.executeNonQueryAsync
        |> ignoreTask

    /// <summary>Execute a query that returns a scalar value</summary>
    /// <param name="query">The query to retrieve the value</param>
    /// <param name="parameters">Parameters to use for the query</param>
    /// <param name="mapFunc">The mapping function to obtain the value</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The scalar value for the query</returns>
    [<CompiledName "FSharpScalar">]
    let scalar<'T when 'T: struct> query parameters (mapFunc: RowReader -> 'T) sqlProps =
        Sql.query query sqlProps
        |> Sql.parameters (FSharpList.ofSeq parameters)
        |> Sql.executeRowAsync mapFunc

    /// <summary>Execute a query that returns a scalar value</summary>
    /// <param name="query">The query to retrieve the value</param>
    /// <param name="parameters">Parameters to use for the query</param>
    /// <param name="mapFunc">The mapping function to obtain the value</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The scalar value for the query</returns>
    let Scalar<'T when 'T: struct>(query, parameters, mapFunc: System.Func<RowReader, 'T>, sqlProps) =
        scalar<'T> query parameters mapFunc.Invoke sqlProps

/// <summary>Table and index definition commands</summary>
module Definition =

    /// <summary>Create a document table</summary>
    /// <param name="name">The table whose existence should be ensured (may include schema)</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "EnsureTable">]
    let ensureTable name sqlProps = backgroundTask {
        do! Custom.nonQuery (Query.Definition.ensureTable name) [] sqlProps
        do! Custom.nonQuery (Query.Definition.ensureKey name PostgreSQL) [] sqlProps
    }

    /// <summary>Create an index on documents in the specified table</summary>
    /// <param name="name">The table to be indexed (may include schema)</param>
    /// <param name="idxType">The type of document index to create</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "EnsureDocumentIndex">]
    let ensureDocumentIndex name idxType sqlProps =
        Custom.nonQuery (Query.Definition.ensureDocumentIndex name idxType) [] sqlProps

    /// <summary>Create an index on field(s) within documents in the specified table</summary>
    /// <param name="tableName">The table to be indexed (may include schema)</param>
    /// <param name="indexName">The name of the index to create</param>
    /// <param name="fields">One or more fields to be indexed</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "EnsureFieldIndex">]
    let ensureFieldIndex tableName indexName fields sqlProps =
        Custom.nonQuery (Query.Definition.ensureIndexOn tableName indexName fields PostgreSQL) [] sqlProps

/// <summary>Commands to add documents</summary>
[<AutoOpen>]
module Document =

    /// <summary>Insert a new document</summary>
    /// <param name="tableName">The table into which the document should be inserted (may include schema)</param>
    /// <param name="document">The document to be inserted</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "Insert">]
    let insert<'TDoc> tableName (document: 'TDoc) sqlProps =
        let query =
            match Configuration.autoIdStrategy () with
            | Disabled -> Query.insert tableName
            | strategy ->
                let idField   = Configuration.idField ()
                let dataParam =
                    if AutoId.NeedsAutoId strategy document idField then
                        match strategy with
                        | Number ->
                            $"' || (SELECT COALESCE(MAX((data->>'{idField}')::numeric), 0) + 1 FROM {tableName}) || '"
                        | Guid -> $"\"{AutoId.GenerateGuid()}\""
                        | RandomString -> $"\"{AutoId.GenerateRandomString(Configuration.idStringLength ())}\""
                        | Disabled -> "@data"
                        |> function it -> $"""@data::jsonb || ('{{"{idField}":{it}}}')::jsonb"""
                    else "@data"
                (Query.insert tableName).Replace("@data", dataParam)
        Custom.nonQuery query [ jsonParam "@data" document ] sqlProps

    /// <summary>Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")</summary>
    /// <param name="tableName">The table into which the document should be saved (may include schema)</param>
    /// <param name="document">The document to be saved</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "Save">]
    let save<'TDoc> tableName (document: 'TDoc) sqlProps =
        Custom.nonQuery (Query.save tableName) [ jsonParam "@data" document ] sqlProps

/// <summary>Commands to count documents</summary>
[<RequireQualifiedAccess>]
module Count =

    /// <summary>Count all documents in a table</summary>
    /// <param name="tableName">The table in which documents should be counted (may include schema)</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The count of the documents in the table</returns>
    [<CompiledName "All">]
    let all tableName sqlProps =
        Custom.scalar (Query.count tableName) [] toCount sqlProps

    /// <summary>Count matching documents using JSON field comparisons (<c>-&gt;&gt; =</c>, etc.)</summary>
    /// <param name="tableName">The table in which documents should be counted (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="fields">The field conditions to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The count of matching documents in the table</returns>
    [<CompiledName "ByFields">]
    let byFields tableName howMatched fields sqlProps =
        Custom.scalar
            (Query.byFields (Query.count tableName) howMatched fields) (addFieldParams fields []) toCount sqlProps

    /// <summary>Count matching documents using a JSON containment query (<c>@&gt;</c>)</summary>
    /// <param name="tableName">The table in which documents should be counted (may include schema)</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The count of the documents in the table</returns>
    [<CompiledName "ByContains">]
    let byContains tableName (criteria: 'TContains) sqlProps =
        Custom.scalar
            (Query.byContains (Query.count tableName)) [ jsonParam "@criteria" criteria ] toCount sqlProps

    /// <summary>Count matching documents using a JSON Path match query (<c>@?</c>)</summary>
    /// <param name="tableName">The table in which documents should be counted (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to be matched</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The count of the documents in the table</returns>
    [<CompiledName "ByJsonPath">]
    let byJsonPath tableName jsonPath sqlProps =
        Custom.scalar
            (Query.byPathMatch (Query.count tableName)) [ "@path", Sql.string jsonPath ] toCount sqlProps

/// <summary>Commands to determine if documents exist</summary>
[<RequireQualifiedAccess>]
module Exists =

    /// <summary>Determine if a document exists for the given ID</summary>
    /// <param name="tableName">The table in which existence should be checked (may include schema)</param>
    /// <param name="docId">The ID of the document whose existence should be checked</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>True if a document exists, false if not</returns>
    [<CompiledName "ById">]
    let byId tableName (docId: 'TKey) sqlProps =
        Custom.scalar (Query.exists tableName (Query.whereById docId)) [ idParam docId ] toExists sqlProps

    /// <summary>Determine if a document exists using JSON field comparisons (<c>-&gt;&gt; =</c>, etc.)</summary>
    /// <param name="tableName">The table in which existence should be checked (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="fields">The field conditions to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>True if any matching documents exist, false if not</returns>
    [<CompiledName "ByFields">]
    let byFields tableName howMatched fields sqlProps =
        Custom.scalar
            (Query.exists tableName (Query.whereByFields howMatched fields))
            (addFieldParams fields [])
            toExists
            sqlProps

    /// <summary>Determine if a document exists using a JSON containment query (<c>@&gt;</c>)</summary>
    /// <param name="tableName">The table in which existence should be checked (may include schema)</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>True if any matching documents exist, false if not</returns>
    [<CompiledName "ByContains">]
    let byContains tableName (criteria: 'TContains) sqlProps =
        Custom.scalar
            (Query.exists tableName (Query.whereDataContains "@criteria"))
            [ jsonParam "@criteria" criteria ]
            toExists
            sqlProps

    /// <summary>Determine if a document exists using a JSON Path match query (<c>@?</c>)</summary>
    /// <param name="tableName">The table in which existence should be checked (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to be matched</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>True if any matching documents exist, false if not</returns>
    [<CompiledName "ByJsonPath">]
    let byJsonPath tableName jsonPath sqlProps =
        Custom.scalar
            (Query.exists tableName (Query.whereJsonPathMatches "@path"))
            [ "@path", Sql.string jsonPath ]
            toExists
            sqlProps

/// <summary>Commands to retrieve documents as domain objects</summary>
[<RequireQualifiedAccess>]
module Find =

    /// <summary>Retrieve all documents in the given table</summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents from the given table</returns>
    [<CompiledName "FSharpAll">]
    let all<'TDoc> tableName sqlProps =
        Custom.list<'TDoc> (Query.find tableName) [] fromData<'TDoc> sqlProps

    /// <summary>Retrieve all documents in the given table</summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents from the given table</returns>
    let All<'TDoc>(tableName, sqlProps) =
        Custom.List<'TDoc>(Query.find tableName, [], fromData<'TDoc>, sqlProps)

    /// <summary>Retrieve all documents in the given table ordered by the given fields in the document</summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents from the given table, ordered by the given fields</returns>
    [<CompiledName "FSharpAllOrdered">]
    let allOrdered<'TDoc> tableName orderFields sqlProps =
        Custom.list<'TDoc> (Query.find tableName + Query.orderBy orderFields PostgreSQL) [] fromData<'TDoc> sqlProps

    /// <summary>Retrieve all documents in the given table ordered by the given fields in the document</summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents from the given table, ordered by the given fields</returns>
    let AllOrdered<'TDoc>(tableName, orderFields, sqlProps) =
        Custom.List<'TDoc>(
            Query.find tableName + Query.orderBy orderFields PostgreSQL, [], fromData<'TDoc>, sqlProps)

    /// <summary>Retrieve a document by its ID</summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="docId">The ID of the document to retrieve</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns><c>Some</c> with the document if found, <c>None</c> otherwise</returns>
    [<CompiledName "FSharpById">]
    let byId<'TKey, 'TDoc> tableName (docId: 'TKey) sqlProps =
        Custom.single (Query.byId (Query.find tableName) docId) [ idParam docId ] fromData<'TDoc> sqlProps

    /// <summary>Retrieve a document by its ID</summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="docId">The ID of the document to retrieve</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The document if found, <c>null</c> otherwise</returns>
    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)

    /// <summary>Retrieve documents matching JSON field comparisons (<c>-&gt;&gt; =</c>, etc.)</summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="fields">The field conditions to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents matching the given fields</returns>
    [<CompiledName "FSharpByFields">]
    let byFields<'TDoc> tableName howMatched fields sqlProps =
        Custom.list<'TDoc>
            (Query.byFields (Query.find tableName) howMatched fields)
            (addFieldParams fields [])
            fromData<'TDoc>
            sqlProps

    /// <summary>Retrieve documents matching JSON field comparisons (<c>-&gt;&gt; =</c>, etc.)</summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="fields">The field conditions to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents matching the given fields</returns>
    let ByFields<'TDoc>(tableName, howMatched, fields, sqlProps) =
        Custom.List<'TDoc>(
            Query.byFields (Query.find tableName) howMatched fields,
            addFieldParams fields [],
            fromData<'TDoc>,
            sqlProps)

    /// <summary>
    /// Retrieve documents matching JSON field comparisons (<c>-&gt;&gt; =</c>, etc.) ordered by the given fields in
    /// the document
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="queryFields">The field conditions to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents matching the given fields, ordered by the other given fields</returns>
    [<CompiledName "FSharpByFieldsOrdered">]
    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

    /// <summary>
    /// Retrieve documents matching JSON field comparisons (<c>-&gt;&gt; =</c>, etc.) ordered by the given fields in the
    /// document
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="queryFields">The field conditions to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents matching the given fields, ordered by the other given fields</returns>
    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)

    /// <summary>Retrieve documents matching a JSON containment query (<c>@&gt;</c>)</summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents matching the given containment query</returns>
    [<CompiledName "FSharpByContains">]
    let byContains<'TDoc> tableName (criteria: obj) sqlProps =
        Custom.list<'TDoc>
            (Query.byContains (Query.find tableName)) [ jsonParam "@criteria" criteria ] fromData<'TDoc> sqlProps

    /// <summary>Retrieve documents matching a JSON containment query (<c>@&gt;</c>)</summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents matching the given containment query</returns>
    let ByContains<'TDoc>(tableName, criteria: obj, sqlProps) =
        Custom.List<'TDoc>(
            Query.byContains (Query.find tableName),
            [ jsonParam "@criteria" criteria ],
            fromData<'TDoc>,
            sqlProps)

    /// <summary>
    /// Retrieve documents matching a JSON containment query (<c>@&gt;</c>) ordered by the given fields in the document
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents matching the given containment query, ordered by the given fields</returns>
    [<CompiledName "FSharpByContainsOrdered">]
    let byContainsOrdered<'TDoc> tableName (criteria: obj) orderFields sqlProps =
        Custom.list<'TDoc>
            (Query.byContains (Query.find tableName) + Query.orderBy orderFields PostgreSQL)
            [ jsonParam "@criteria" criteria ]
            fromData<'TDoc>
            sqlProps

    /// <summary>
    /// Retrieve documents matching a JSON containment query (<c>@&gt;</c>) ordered by the given fields in the document
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents matching the given containment query, ordered by the given fields</returns>
    let ByContainsOrdered<'TDoc>(tableName, criteria: obj, orderFields, sqlProps) =
        Custom.List<'TDoc>(
            Query.byContains (Query.find tableName) + Query.orderBy orderFields PostgreSQL,
            [ jsonParam "@criteria" criteria ],
            fromData<'TDoc>,
            sqlProps)

    /// <summary>Retrieve documents matching a JSON Path match query (<c>@?</c>)</summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents matching the given JSON Path expression</returns>
    [<CompiledName "FSharpByJsonPath">]
    let byJsonPath<'TDoc> tableName jsonPath sqlProps =
        Custom.list<'TDoc>
            (Query.byPathMatch (Query.find tableName)) [ "@path", Sql.string jsonPath ] fromData<'TDoc> sqlProps

    /// <summary>Retrieve documents matching a JSON Path match query (<c>@?</c>)</summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents matching the given JSON Path expression</returns>
    let ByJsonPath<'TDoc>(tableName, jsonPath, sqlProps) =
        Custom.List<'TDoc>(
            Query.byPathMatch (Query.find tableName),
            [ "@path", Sql.string jsonPath ],
            fromData<'TDoc>,
            sqlProps)

    /// <summary>
    /// Retrieve documents matching a JSON Path match query (<c>@?</c>) ordered by the given fields in the document
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents matching the given JSON Path expression, ordered by the given fields</returns>
    [<CompiledName "FSharpByJsonPathOrdered">]
    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

    /// <summary>
    /// Retrieve documents matching a JSON Path match query (<c>@?</c>) ordered by the given fields in the document
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents matching the given JSON Path expression, ordered by the given fields</returns>
    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)

    /// <summary>Retrieve the first document matching JSON field comparisons (<c>-&gt;&gt; =</c>, etc.)</summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="fields">The field conditions to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns><c>Some</c> with the first document, or <c>None</c> if not found</returns>
    [<CompiledName "FSharpFirstByFields">]
    let firstByFields<'TDoc> tableName howMatched fields sqlProps =
        Custom.single<'TDoc>
            (Query.byFields (Query.find tableName) howMatched fields)
            (addFieldParams fields [])
            fromData<'TDoc>
            sqlProps

    /// <summary>Retrieve the first document matching JSON field comparisons (<c>-&gt;&gt; =</c>, etc.)</summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="fields">The field conditions to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The first document, or <c>null</c> if not found</returns>
    let FirstByFields<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, howMatched, fields, sqlProps) =
        Custom.Single<'TDoc>(
            Query.byFields (Query.find tableName) howMatched fields,
            addFieldParams fields [],
            fromData<'TDoc>,
            sqlProps)

    /// <summary>
    /// Retrieve the first document matching JSON field comparisons (<c>-&gt;&gt; =</c>, etc.) ordered by the given
    /// fields in the document
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="queryFields">The field conditions to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns><c>Some</c> with the first document ordered by the given fields, or <c>None</c> if not found</returns>
    [<CompiledName "FSharpFirstByFieldsOrdered">]
    let firstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields sqlProps =
        Custom.single<'TDoc>
            (Query.byFields (Query.find tableName) howMatched queryFields + Query.orderBy orderFields PostgreSQL)
            (addFieldParams queryFields [])
            fromData<'TDoc>
            sqlProps

    /// <summary>
    /// Retrieve the first document matching JSON field comparisons (<c>-&gt;&gt; =</c>, etc.) ordered by the given
    /// fields in the document
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="queryFields">The field conditions to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The first document ordered by the given fields, or <c>null</c> if not found</returns>
    let FirstByFieldsOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(
            tableName, howMatched, queryFields, orderFields, sqlProps) =
        Custom.Single<'TDoc>(
            Query.byFields (Query.find tableName) howMatched queryFields + Query.orderBy orderFields PostgreSQL,
            addFieldParams queryFields [],
            fromData<'TDoc>,
            sqlProps)

    /// <summary>Retrieve the first document matching a JSON containment query (<c>@&gt;</c>)</summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns><c>Some</c> with the first document, or <c>None</c> if not found</returns>
    [<CompiledName "FSharpFirstByContains">]
    let firstByContains<'TDoc> tableName (criteria: obj) sqlProps =
        Custom.single<'TDoc>
            (Query.byContains (Query.find tableName)) [ jsonParam "@criteria" criteria ] fromData<'TDoc> sqlProps

    /// <summary>Retrieve the first document matching a JSON containment query (<c>@&gt;</c>)</summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The first document, or <c>null</c> if not found</returns>
    let FirstByContains<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, criteria: obj, sqlProps) =
        Custom.Single<'TDoc>(
            Query.byContains (Query.find tableName), [ jsonParam "@criteria" criteria ], fromData<'TDoc>, sqlProps)

    /// <summary>
    /// Retrieve the first document matching a JSON containment query (<c>@&gt;</c>) ordered by the given fields in the
    /// document
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns><c>Some</c> with the first document ordered by the given fields, or <c>None</c> if not found</returns>
    [<CompiledName "FSharpFirstByContainsOrdered">]
    let firstByContainsOrdered<'TDoc> tableName (criteria: obj) orderFields sqlProps =
        Custom.single<'TDoc>
            (Query.byContains (Query.find tableName) + Query.orderBy orderFields PostgreSQL)
            [ jsonParam "@criteria" criteria ]
            fromData<'TDoc>
            sqlProps

    /// <summary>
    /// Retrieve the first document matching a JSON containment query (<c>@&gt;</c>) ordered by the given fields in the
    /// document
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The first document ordered by the given fields, or <c>null</c> if not found</returns>
    let FirstByContainsOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(
            tableName, criteria: obj, orderFields, sqlProps) =
        Custom.Single<'TDoc>(
            Query.byContains (Query.find tableName) + Query.orderBy orderFields PostgreSQL,
            [ jsonParam "@criteria" criteria ],
            fromData<'TDoc>,
            sqlProps)

    /// <summary>Retrieve the first document matching a JSON Path match query (<c>@?</c>)</summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns><c>Some</c> with the first document, or <c>None</c> if not found</returns>
    [<CompiledName "FSharpFirstByJsonPath">]
    let firstByJsonPath<'TDoc> tableName jsonPath sqlProps =
        Custom.single<'TDoc>
            (Query.byPathMatch (Query.find tableName))
            [ "@path", Sql.string jsonPath ]
            fromData<'TDoc>
            sqlProps

    /// <summary>Retrieve the first document matching a JSON Path match query (<c>@?</c>)</summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The first document, or <c>null</c> if not found</returns>
    let FirstByJsonPath<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, jsonPath, sqlProps) =
        Custom.Single<'TDoc>(
            Query.byPathMatch (Query.find tableName),
            [ "@path", Sql.string jsonPath ],
            fromData<'TDoc>,
            sqlProps)

    /// <summary>
    /// Retrieve the first document matching a JSON Path match query (<c>@?</c>) ordered by the given fields in the
    /// document
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns><c>Some</c> with the first document ordered by the given fields, or <c>None</c> if not found</returns>
    [<CompiledName "FSharpFirstByJsonPathOrdered">]
    let firstByJsonPathOrdered<'TDoc> tableName jsonPath orderFields sqlProps =
        Custom.single<'TDoc>
            (Query.byPathMatch (Query.find tableName) + Query.orderBy orderFields PostgreSQL)
            [ "@path", Sql.string jsonPath ]
            fromData<'TDoc>
            sqlProps

    /// <summary>
    /// Retrieve the first document matching a JSON Path match query (<c>@?</c>) ordered by the given fields in the
    /// document
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The first document ordered by the given fields, or <c>null</c> if not found</returns>
    let FirstByJsonPathOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(
            tableName, jsonPath, orderFields, sqlProps) =
        Custom.Single<'TDoc>(
            Query.byPathMatch (Query.find tableName) + Query.orderBy orderFields PostgreSQL,
            [ "@path", Sql.string jsonPath ],
            fromData<'TDoc>,
            sqlProps)

/// <summary>Commands to retrieve documents as JSON</summary>
[<RequireQualifiedAccess>]
module Json =

    /// <summary>Retrieve all documents in the given table as a JSON array</summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents from the given table as a JSON array</returns>
    [<CompiledName "All">]
    let all tableName sqlProps =
        Custom.jsonArray (Query.find tableName) [] jsonFromData sqlProps

    /// <summary>Write all documents in the given table to the given <c>PipeWriter</c></summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteAll">]
    let writeAll tableName writer sqlProps =
        Custom.writeJsonArray (Query.find tableName) [] writer jsonFromData sqlProps

    /// <summary>
    /// Retrieve all documents in the given table as a JSON array, ordered by the given fields in the document
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents from the given table as a JSON array, ordered by the given fields</returns>
    [<CompiledName "AllOrdered">]
    let allOrdered tableName orderFields sqlProps =
        Custom.jsonArray (Query.find tableName + Query.orderBy orderFields PostgreSQL) [] jsonFromData sqlProps

    /// <summary>
    /// Write all documents in the given table to the given <c>PipeWriter</c>, ordered by the given fields in the
    /// document
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteAllOrdered">]
    let writeAllOrdered tableName writer orderFields sqlProps =
        Custom.writeJsonArray
            (Query.find tableName + Query.orderBy orderFields PostgreSQL) [] writer jsonFromData sqlProps

    /// <summary>Retrieve a JSON document by its ID</summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="docId">The ID of the document to retrieve</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The JSON document if found, an empty JSON document otherwise</returns>
    [<CompiledName "ById">]
    let byId<'TKey> tableName (docId: 'TKey) sqlProps =
        Custom.jsonSingle (Query.byId (Query.find tableName) docId) [ idParam docId ] jsonFromData sqlProps

    /// <summary>Write a JSON document to the given <c>PipeWriter</c> by its ID</summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="docId">The ID of the document to retrieve</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteById">]
    let writeById<'TKey> tableName writer (docId: 'TKey) sqlProps = backgroundTask {
        let! json = byId tableName docId sqlProps
        let! _ = PipeWriter.writeString writer json
        ()
    }

    /// <summary>Retrieve JSON documents matching JSON field comparisons (<c>-&gt;&gt; =</c>, etc.)</summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="fields">The field conditions to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All JSON documents matching the given fields</returns>
    [<CompiledName "ByFields">]
    let byFields tableName howMatched fields sqlProps =
        Custom.jsonArray
            (Query.byFields (Query.find tableName) howMatched fields) (addFieldParams fields []) jsonFromData sqlProps

    /// <summary>
    /// Write JSON documents to the given <c>PipeWriter</c> matching JSON field comparisons (<c>-&gt;&gt; =</c>, etc.)
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="fields">The field conditions to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteByFields">]
    let writeByFields tableName writer howMatched fields sqlProps =
        Custom.writeJsonArray
            (Query.byFields (Query.find tableName) howMatched fields)
            (addFieldParams fields [])
            writer
            jsonFromData
            sqlProps

    /// <summary>
    /// Retrieve JSON documents matching JSON field comparisons (<c>-&gt;&gt; =</c>, etc.) ordered by the given fields
    /// in the document
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="queryFields">The field conditions to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All JSON documents matching the given fields, ordered by the other given fields</returns>
    [<CompiledName "ByFieldsOrdered">]
    let byFieldsOrdered tableName howMatched queryFields orderFields sqlProps =
        Custom.jsonArray
            (Query.byFields (Query.find tableName) howMatched queryFields + Query.orderBy orderFields PostgreSQL)
            (addFieldParams queryFields [])
            jsonFromData
            sqlProps

    /// <summary>
    /// Write JSON documents to the given <c>PipeWriter</c> matching JSON field comparisons (<c>-&gt;&gt; =</c>, etc.)
    /// ordered by the given fields in the document
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="queryFields">The field conditions to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteByFieldsOrdered">]
    let writeByFieldsOrdered tableName writer howMatched queryFields orderFields sqlProps =
        Custom.writeJsonArray
            (Query.byFields (Query.find tableName) howMatched queryFields + Query.orderBy orderFields PostgreSQL)
            (addFieldParams queryFields [])
            writer
            jsonFromData
            sqlProps

    /// <summary>Retrieve JSON documents matching a JSON containment query (<c>@&gt;</c>)</summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All JSON documents matching the given containment query</returns>
    [<CompiledName "ByContains">]
    let byContains tableName (criteria: obj) sqlProps =
        Custom.jsonArray
            (Query.byContains (Query.find tableName)) [ jsonParam "@criteria" criteria ] jsonFromData sqlProps

    /// <summary>
    /// Write JSON documents to the given <c>PipeWriter</c> matching a JSON containment query (<c>@&gt;</c>)
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteByContains">]
    let writeByContains tableName writer (criteria: obj) sqlProps =
        Custom.writeJsonArray
            (Query.byContains (Query.find tableName)) [ jsonParam "@criteria" criteria ] writer jsonFromData sqlProps

    /// <summary>
    /// Retrieve JSON documents matching a JSON containment query (<c>@&gt;</c>) ordered by the given fields in the
    /// document
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All documents matching the given containment query, ordered by the given fields</returns>
    [<CompiledName "ByContainsOrdered">]
    let byContainsOrdered tableName (criteria: obj) orderFields sqlProps =
        Custom.jsonArray
            (Query.byContains (Query.find tableName) + Query.orderBy orderFields PostgreSQL)
            [ jsonParam "@criteria" criteria ]
            jsonFromData
            sqlProps

    /// <summary>
    /// Write JSON documents to the given <c>PipeWriter</c> matching a JSON containment query (<c>@&gt;</c>) ordered by
    /// the given fields in the document
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteByContainsOrdered">]
    let writeByContainsOrdered tableName writer (criteria: obj) orderFields sqlProps =
        Custom.writeJsonArray
            (Query.byContains (Query.find tableName) + Query.orderBy orderFields PostgreSQL)
            [ jsonParam "@criteria" criteria ]
            writer
            jsonFromData
            sqlProps

    /// <summary>Retrieve JSON documents matching a JSON Path match query (<c>@?</c>)</summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All JSON documents matching the given JSON Path expression</returns>
    [<CompiledName "ByJsonPath">]
    let byJsonPath tableName jsonPath sqlProps =
        Custom.jsonArray
            (Query.byPathMatch (Query.find tableName)) [ "@path", Sql.string jsonPath ] jsonFromData sqlProps

    /// <summary>
    /// Write JSON documents to the given <c>PipeWriter</c> matching a JSON Path match query (<c>@?</c>)
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteByJsonPath">]
    let writeByJsonPath tableName writer jsonPath sqlProps =
        Custom.writeJsonArray
            (Query.byPathMatch (Query.find tableName)) [ "@path", Sql.string jsonPath ] writer jsonFromData sqlProps

    /// <summary>
    /// Retrieve JSON documents matching a JSON Path match query (<c>@?</c>) ordered by the given fields in the document
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>All JSON documents matching the given JSON Path expression, ordered by the given fields</returns>
    [<CompiledName "ByJsonPathOrdered">]
    let byJsonPathOrdered tableName jsonPath orderFields sqlProps =
        Custom.jsonArray
            (Query.byPathMatch (Query.find tableName) + Query.orderBy orderFields PostgreSQL)
            [ "@path", Sql.string jsonPath ]
            jsonFromData
            sqlProps

    /// <summary>
    /// Write JSON documents to the given <c>PipeWriter</c> matching a JSON Path match query (<c>@?</c>) ordered by the
    /// given fields in the document
    /// </summary>
    /// <param name="tableName">The table from which documents should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteByJsonPathOrdered">]
    let writeByJsonPathOrdered tableName writer jsonPath orderFields sqlProps =
        Custom.writeJsonArray
            (Query.byPathMatch (Query.find tableName) + Query.orderBy orderFields PostgreSQL)
            [ "@path", Sql.string jsonPath ]
            writer
            jsonFromData
            sqlProps

    /// <summary>Retrieve the first JSON document matching JSON field comparisons (<c>-&gt;&gt; =</c>, etc.)</summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="fields">The field conditions to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The first matching JSON document if found, an empty JSON document otherwise</returns>
    [<CompiledName "FirstByFields">]
    let firstByFields tableName howMatched fields sqlProps =
        Custom.jsonSingle
            (Query.byFields (Query.find tableName) howMatched fields) (addFieldParams fields []) jsonFromData sqlProps

    /// <summary>
    /// Write the first JSON document to the given <c>PipeWriter</c> matching JSON field comparisons(<c>-&gt;&gt; =</c>,
    /// etc.)
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="fields">The field conditions to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteFirstByFields">]
    let writeFirstByFields tableName writer howMatched fields sqlProps = backgroundTask {
        let! json = firstByFields tableName howMatched fields sqlProps
        let! _ = PipeWriter.writeString writer json
        ()
    }

    /// <summary>
    /// Retrieve the first JSON document matching JSON field comparisons (<c>-&gt;&gt; =</c>, etc.) ordered by the given
    /// fields in the document
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="queryFields">The field conditions to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The first matching JSON document if found, an empty JSON document otherwise</returns>
    [<CompiledName "FirstByFieldsOrdered">]
    let firstByFieldsOrdered tableName howMatched queryFields orderFields sqlProps =
        Custom.jsonSingle
            (Query.byFields (Query.find tableName) howMatched queryFields + Query.orderBy orderFields PostgreSQL)
            (addFieldParams queryFields [])
            jsonFromData
            sqlProps

    /// <summary>
    /// Write the first JSON document to the given <c>PipeWriter</c> matching JSON field comparisons
    /// (<c>-&gt;&gt; =</c>, etc.) ordered by the given fields in the document
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="queryFields">The field conditions to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteFirstByFieldsOrdered">]
    let writeFirstByFieldsOrdered tableName writer howMatched queryFields orderFields sqlProps = backgroundTask {
        let! json = firstByFieldsOrdered tableName howMatched queryFields orderFields sqlProps
        let! _ = PipeWriter.writeString writer json
        ()
    }

    /// <summary>Retrieve the first JSON document matching a JSON containment query (<c>@&gt;</c>)</summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The first matching JSON document if found, an empty JSON document otherwise</returns>
    [<CompiledName "FirstByContains">]
    let firstByContains tableName (criteria: obj) sqlProps =
        Custom.jsonSingle
            (Query.byContains (Query.find tableName)) [ jsonParam "@criteria" criteria ] jsonFromData sqlProps

    /// <summary>
    /// Write the first JSON document to the given <c>PipeWriter</c> matching a JSON containment query (<c>@&gt;</c>)
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteFirstByContains">]
    let writeFirstByContains tableName writer (criteria: obj) sqlProps = backgroundTask {
        let! json = firstByContains tableName criteria sqlProps
        let! _ = PipeWriter.writeString writer json
        ()
    }

    /// <summary>
    /// Retrieve the first JSON document matching a JSON containment query (<c>@&gt;</c>) ordered by the given fields in
    /// the document
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The first matching JSON document if found, an empty JSON document otherwise</returns>
    [<CompiledName "FirstByContainsOrdered">]
    let firstByContainsOrdered tableName (criteria: obj) orderFields sqlProps =
        Custom.jsonSingle
            (Query.byContains (Query.find tableName) + Query.orderBy orderFields PostgreSQL)
            [ jsonParam "@criteria" criteria ]
            jsonFromData
            sqlProps

    /// <summary>
    /// Write the first JSON document to the given <c>PipeWriter</c> matching a JSON containment query (<c>@&gt;</c>)
    /// ordered by the given fields in the document
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="criteria">The document to match with the containment query</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteFirstByContainsOrdered">]
    let writeFirstByContainsOrdered tableName writer (criteria: obj) orderFields sqlProps = backgroundTask {
        let! json = firstByContainsOrdered tableName criteria orderFields sqlProps
        let! _ = PipeWriter.writeString writer json
        ()
    }

    /// <summary>Retrieve the first JSON document matching a JSON Path match query (<c>@?</c>)</summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The first matching JSON document if found, an empty JSON document otherwise</returns>
    [<CompiledName "FirstByJsonPath">]
    let firstByJsonPath tableName jsonPath sqlProps =
        Custom.jsonSingle
            (Query.byPathMatch (Query.find tableName)) [ "@path", Sql.string jsonPath ] jsonFromData sqlProps

    /// <summary>
    /// Write the first JSON document to the given <c>PipeWriter</c> matching a JSON Path match query (<c>@?</c>)
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteFirstByJsonPath">]
    let writeFirstByJsonPath tableName writer jsonPath sqlProps = backgroundTask {
        let! json = firstByJsonPath tableName jsonPath sqlProps
        let! _ = PipeWriter.writeString writer json
        ()
    }

    /// <summary>
    /// Retrieve the first JSON document matching a JSON Path match query (<c>@?</c>) ordered by the given fields in the
    /// document
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    /// <returns>The first matching JSON document if found, an empty JSON document otherwise</returns>
    [<CompiledName "FirstByJsonPathOrdered">]
    let firstByJsonPathOrdered tableName jsonPath orderFields sqlProps =
        Custom.jsonSingle
            (Query.byPathMatch (Query.find tableName) + Query.orderBy orderFields PostgreSQL)
            [ "@path", Sql.string jsonPath ]
            jsonFromData
            sqlProps

    /// <summary>
    /// Write the first JSON document to the given <c>PipeWriter</c> matching a JSON Path match query (<c>@?</c>)
    /// ordered by the given fields in the document
    /// </summary>
    /// <param name="tableName">The table from which a document should be retrieved (may include schema)</param>
    /// <param name="writer">The PipeWriter to which the results should be written</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="orderFields">Fields by which the results should be ordered</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "WriteFirstByJsonPathOrdered">]
    let writeFirstByJsonPathOrdered tableName writer jsonPath orderFields sqlProps = backgroundTask {
        let! json = firstByJsonPathOrdered tableName jsonPath orderFields sqlProps
        let! _ = PipeWriter.writeString writer json
        ()
    }

/// <summary>Commands to update documents</summary>
[<RequireQualifiedAccess>]
module Update =

    /// <summary>Update (replace) an entire document by its ID</summary>
    /// <param name="tableName">The table in which a document should be updated (may include schema)</param>
    /// <param name="docId">The ID of the document to be updated (replaced)</param>
    /// <param name="document">The new document</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "ById">]
    let byId tableName (docId: 'TKey) (document: 'TDoc) sqlProps =
        Custom.nonQuery
            (Query.byId (Query.update tableName) docId) [ idParam docId; jsonParam "@data" document ] sqlProps

    /// <summary>
    /// Update (replace) an entire document by its ID, using the provided function to obtain the ID from the document
    /// </summary>
    /// <param name="tableName">The table in which a document should be updated (may include schema)</param>
    /// <param name="idFunc">The function to obtain the ID of the document</param>
    /// <param name="document">The new document</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "FSharpByFunc">]
    let byFunc tableName (idFunc: 'TDoc -> 'TKey) (document: 'TDoc) sqlProps =
        byId tableName (idFunc document) document sqlProps

    /// <summary>
    /// Update (replace) an entire document by its ID, using the provided function to obtain the ID from the document
    /// </summary>
    /// <param name="tableName">The table in which a document should be updated (may include schema)</param>
    /// <param name="idFunc">The function to obtain the ID of the document</param>
    /// <param name="document">The new document</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    let ByFunc(tableName, idFunc: System.Func<'TDoc, 'TKey>, document: 'TDoc, sqlProps) =
        byFunc tableName idFunc.Invoke document sqlProps

/// <summary>Commands to patch (partially update) documents</summary>
[<RequireQualifiedAccess>]
module Patch =

    /// <summary>Patch a document by its ID</summary>
    /// <param name="tableName">The table in which a document should be patched (may include schema)</param>
    /// <param name="docId">The ID of the document to patch</param>
    /// <param name="patch">The partial document to patch the existing document</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "ById">]
    let byId tableName (docId: 'TKey) (patch: 'TPatch) sqlProps =
        Custom.nonQuery
            (Query.byId (Query.patch tableName) docId) [ idParam docId; jsonParam "@data" patch ] sqlProps

    /// <summary>
    /// Patch documents using a JSON field comparison query in the <c>WHERE</c> clause (<c>-&gt;&gt; =</c>, etc.)
    /// </summary>
    /// <param name="tableName">The table in which documents should be patched (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="fields">The field conditions to match</param>
    /// <param name="patch">The partial document to patch the existing document</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "ByFields">]
    let byFields tableName howMatched fields (patch: 'TPatch) sqlProps =
        Custom.nonQuery
            (Query.byFields (Query.patch tableName) howMatched fields)
            (addFieldParams fields [ jsonParam "@data" patch ])
            sqlProps

    /// <summary>Patch documents using a JSON containment query in the <c>WHERE</c> clause (<c>@&gt;</c>)</summary>
    /// <param name="tableName">The table in which documents should be patched (may include schema)</param>
    /// <param name="criteria">The document to match the containment query</param>
    /// <param name="patch">The partial document to patch the existing document</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "ByContains">]
    let byContains tableName (criteria: 'TContains) (patch: 'TPatch) sqlProps =
        Custom.nonQuery
            (Query.byContains (Query.patch tableName))
            [ jsonParam "@data" patch; jsonParam "@criteria" criteria ]
            sqlProps

    /// <summary>Patch documents using a JSON Path match query in the <c>WHERE</c> clause (<c>@?</c>)</summary>
    /// <param name="tableName">The table in which documents should be patched (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="patch">The partial document to patch the existing document</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "ByJsonPath">]
    let byJsonPath tableName jsonPath (patch: 'TPatch) sqlProps =
        Custom.nonQuery
            (Query.byPathMatch (Query.patch tableName))
            [ jsonParam "@data" patch; "@path", Sql.string jsonPath ]
            sqlProps

/// <summary>Commands to remove fields from documents</summary>
[<RequireQualifiedAccess>]
module RemoveFields =

    /// <summary>Remove fields from a document by the document's ID</summary>
    /// <param name="tableName">The table in which a document should be modified (may include schema)</param>
    /// <param name="docId">The ID of the document to modify</param>
    /// <param name="fieldNames">One or more field names to remove from the document</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "ById">]
    let byId tableName (docId: 'TKey) fieldNames sqlProps =
        Custom.nonQuery
            (Query.byId (Query.removeFields tableName) docId) [ idParam docId; fieldNameParams fieldNames ] sqlProps

    /// <summary>Remove fields from documents via a comparison on JSON fields in the document</summary>
    /// <param name="tableName">The table in which documents should be modified (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="fields">The field conditions to match</param>
    /// <param name="fieldNames">One or more field names to remove from the matching documents</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "ByFields">]
    let byFields tableName howMatched fields fieldNames sqlProps =
        Custom.nonQuery
            (Query.byFields (Query.removeFields tableName) howMatched fields)
            (addFieldParams fields [ fieldNameParams fieldNames ])
            sqlProps

    /// <summary>Remove fields from documents via a JSON containment query (<c>@&gt;</c>)</summary>
    /// <param name="tableName">The table in which documents should be modified (may include schema)</param>
    /// <param name="criteria">The document to match the containment query</param>
    /// <param name="fieldNames">One or more field names to remove from the matching documents</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "ByContains">]
    let byContains tableName (criteria: 'TContains) fieldNames sqlProps =
        Custom.nonQuery
            (Query.byContains (Query.removeFields tableName))
            [ jsonParam "@criteria" criteria; fieldNameParams fieldNames ]
            sqlProps

    /// <summary>Remove fields from documents via a JSON Path match query (<c>@?</c>)</summary>
    /// <param name="tableName">The table in which documents should be modified (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="fieldNames">One or more field names to remove from the matching documents</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "FSharpByJsonPath">]
    let byJsonPath tableName jsonPath fieldNames sqlProps =
        Custom.nonQuery
            (Query.byPathMatch (Query.removeFields tableName))
            [ "@path", Sql.string jsonPath; fieldNameParams fieldNames ]
            sqlProps

/// <summary>Commands to delete documents</summary>
[<RequireQualifiedAccess>]
module Delete =

    /// <summary>Delete a document by its ID</summary>
    /// <param name="tableName">The table in which a document should be deleted (may include schema)</param>
    /// <param name="docId">The ID of the document to delete</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "ById">]
    let byId tableName (docId: 'TKey) sqlProps =
        Custom.nonQuery (Query.byId (Query.delete tableName) docId) [ idParam docId ] sqlProps

    /// <summary>Delete documents by matching a JSON field comparison query (<c>-&gt;&gt; =</c>, etc.)</summary>
    /// <param name="tableName">The table in which documents should be deleted (may include schema)</param>
    /// <param name="howMatched">Whether to match any or all of the field conditions</param>
    /// <param name="fields">The field conditions to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "ByFields">]
    let byFields tableName howMatched fields sqlProps =
        Custom.nonQuery
            (Query.byFields (Query.delete tableName) howMatched fields) (addFieldParams fields []) sqlProps

    /// <summary>Delete documents by matching a JSON contains query (<c>@&gt;</c>)</summary>
    /// <param name="tableName">The table in which documents should be deleted (may include schema)</param>
    /// <param name="criteria">The document to match the containment query</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "ByContains">]
    let byContains tableName (criteria: 'TCriteria) sqlProps =
        Custom.nonQuery (Query.byContains (Query.delete tableName)) [ jsonParam "@criteria" criteria ] sqlProps

    /// <summary>Delete documents by matching a JSON Path match query (<c>@?</c>)</summary>
    /// <param name="tableName">The table in which documents should be deleted (may include schema)</param>
    /// <param name="jsonPath">The JSON Path expression to match</param>
    /// <param name="sqlProps">The <c>SqlProps</c> to use to execute the query</param>
    [<CompiledName "ByJsonPath">]
    let byJsonPath tableName jsonPath sqlProps =
        Custom.nonQuery (Query.byPathMatch (Query.delete tableName)) [ "@path", Sql.string jsonPath ] sqlProps