alex-tan / postgrest-queries / Postgrest.Queries

Types


type Param

An individual postgrest parameter.


type alias Params =
List Param

A collection of parameters that make up a postgrest request.


type Selectable

A type representing which attributes and resources you want to select. It also contains parameters that target nested resources.


type ColumnOrder

A type to specify whether you want an order to be ascending or descending, and optionally whether you want nulls to be first or last.


type Value

Type that can be represented in the queries: strings, ints and lists.


type Operator

A type that represents the clause of a query. In name=eq.John the clause would be the part after the equal sign.

Select

select : List Selectable -> Param

A constructor for the select parameter.

P.select
    [ P.attribute "id"
    , P.attribute "title"
    , P.resource "user" <|
        P.attributes
            [ "email"
            , "name"
            ]
    ]

allAttributes : List Selectable

When you want to select all attributes. This is only useful when used to select attributes of a resource or override default parameters in another function since postgrest returns all attributes by default.

attribute : String -> Selectable

When you want to select a certain column.

attributes : List String -> List Selectable

Shorthand for attributes, when you don't need to specify nested resources:

-- Short version
attributes [ "id" "name" ]

-- Long version
[ attribute "id"
, attribute "name"
]

resource : ResourceName -> List Selectable -> Selectable

When you want to select a nested resource with no special parameters for the nested resources. If you do want to specify parameters, see resourceWithParams.

resourceWithParams : ResourceName -> Params -> List Selectable -> Selectable

When you want to select a nested resource with special praameters.

[ P.select
    [ P.resource "sites"
        [ P.resourceWithParams "streams"
            [ P.order [ P.asc "name" ]
            ]
            allAttributes
        ]
    ]
]
    |> toQueryString

-- select=sites(streams(*))&sites.streams.order=name.asc

Converting/combining into something usable

combineParams : Params -> Params -> Params

Takes a default set of params and a custom set of params and prefers the second set. Useful when you're constructing reusable functions that make similar queries.

concatParams : List Params -> Params

Takes a list of Params and combines them, preferring the last sets first.

normalizeParams : Params -> List ( String, String )

Takes Params and returns the parameters as a list of (Key, Value) strings.

toQueryString : Params -> String

Takes Params and returns a query string such as foo=eq.bar&baz=is.true

Param

param : String -> Operator -> Param

A constructor for an individual postgrest parameter.

param "name" (eq (string "John"))

or : List Param -> Param

Join multiple conditions together with or.

[ or
    [ param "age" <| gte <| int 14
    , param "age" <| lte <| int 18
    ]
]
|> toQueryString

-- or=(age.gte.14,age.lte.18)

and : List Param -> Param

Join multiple conditions together with and.

[ and
    [ param "grade" <| gte <| int 90
    , param "student" <| true
    , or
        [ param "age" <| gte <| int 14
        , param "age" <| null
        ]
    ]
]
|> toQueryString

-- and=(grade.gte.90,student.is.true,or(age.gte.14,age.is.null))

nestedParam : List String -> Param -> Param

When you want to specify an operator for a nested resource manually. It is recommended to use resourceWithParams though.

[ select
    [ attribute "*"
    , resource "actors" allAttributes
    ]
, nestedParam [ "actors" ] <| limit 10
, nestedParam [ "actors" ] <| offset 2
]
|> toQueryString
-- "select=*,actors(*)&actors.limit=10&actors.offset=2"

Operators

eq : Value -> Operator

Used to indicate you need a column to be equal to a certain value.

gt : Value -> Operator

Used to indicate you need a column to be greater than a certain value.

gte : Value -> Operator

Used to indicate you need a column to be greater than or equal than a certain value.

inList : (a -> Value) -> List a -> Operator

Used to indicate you need a column to be within a certain list of values.

param "name" <| inList string [ "Chico", "Harpo", "Groucho" ]

-- name=in.(\"Chico\",\"Harpo\",\"Groucho\")"

limit : Basics.Int -> Param

A constructor for the limit parameter.

limit 10

lt : Value -> Operator

Used to indicate you need a column to be less than a certain value.

lte : Value -> Operator

Used to indicate you need a column to be less than or equal than a certain value.

neq : Value -> Operator

Used to indicate you need a column to be not equal to a certain value.

not : Operator -> Operator

Negate a condition.

[ param "my_tsv" <| not <| phfts (Just "english") "The Fat Cats"
]
|> toQueryString
-- my_tsv=not.phfts(english).The%20Fat%20Cats

true : Operator

When you need a column value to be true

-- foo=is.true
[ P.param "foo" P.true ]
    |> toQueryString

false : Operator

When you need a column value to be false

-- foo=is.false
[ P.param "foo" P.false ]
    |> toQueryString

null : Operator

When a value needs to be null

param "age" <| null

value : Value -> Operator

When you don't want to use a specific type after the equals sign in the query, you can use value to set anything you want.

offset : Basics.Int -> Param

Offset

ilike : String -> Operator

ILIKE operator (use * in place of %)

param "text" <| ilike "foo*bar"

like : String -> Operator

LIKE operator (use * in place of %)

param "text" <| like "foo*bar"

Values

string : String -> Value

Normalize a string into a postgrest value.

int : Basics.Int -> Value

Normalize an int into a postgrest value.

list : List Value -> Value

This is available if you need it, but more likely you'll want to use inList.

Order

order : List ColumnOrder -> Param

A constructor for the limit parameter.

order (asc "name")

order (desc "name")

asc : String -> ColumnOrder

Used in combination with order to sort results ascending.

desc : String -> ColumnOrder

Used in combination with order to sort results descending.

nullsfirst : ColumnOrder -> ColumnOrder

Sort so that nulls will come first.

order [ asc "age" |> nullsfirst ]

nullslast : ColumnOrder -> ColumnOrder

Sort so that nulls will come last.

order [ asc "age" |> nullslast ]

Full-Text Search

plfts : Maybe Language -> String -> Operator

Full-Text Search using plainto_tsquery

phfts : Maybe Language -> String -> Operator

Full-Text Search using phraseto_tsquery

fts : Maybe Language -> String -> Operator

Full-Text Search using to_tsquery

[ param "my_tsv" <| fts (Just "french") "amusant" ]
    |> toQueryString

"my_tsv=fts(french).amusant"