Field functions¶

Field functions allow users to manipulate and extract data from fields when applying sorting and filtering operations. This section describes the available functions and their usage with the FunQL language.

Datetime functions¶

These functions extract specific components from DateTime values, such as the year, month, or hour.

Function list¶

Name	Summary
`year`	Returns the year component of a `DateTime` value.
`month`	Returns the month component of a `DateTime` value.
`day`	Returns the day of the month component of a `DateTime` value.
`hour`	Returns the hour component of a `DateTime` value.
`minute`	Returns the minute component of a `DateTime` value.
`second`	Returns the second component of a `DateTime` value.
`millisecond`	Returns the millisecond component of a `DateTime` value.

year¶

The year function has the following signature:

year(field: DateTime): Integer

The year function returns the year component of a DateTime parameter value.

For example:

set.json

{
  "name": "LEGO Star Wars Millennium Falcon",
  "setNumber": 75192,
  "price": 849.99,
  "launchTime": "2017-10-01T14:15:30.500Z"
}

year(launchTime)

Returns 2017.

Usage

Return all sets that were launched in 2017:

RESTQL

GET https://api.play.funql.io/sets?filter=eq(year(launchTime), 2017)

POST https://api.play.funql.io/funql
Content-Type: text/plain

listSets(
  filter(
    eq(year(launchTime), 2017)
  )
)

month¶

The month function has the following signature:

month(field: DateTime): Integer

The month function returns the month component of a DateTime parameter value. The month is given as an integer, ranging from 1 (January) to 12 (December).

For example:

set.json

{
  "name": "LEGO Star Wars Millennium Falcon",
  "setNumber": 75192,
  "price": 849.99,
  "launchTime": "2017-10-01T14:15:30.500Z"
}

month(launchTime)

Returns 10.

Usage

Return all sets that were launched in October, the 10th month of the year:

RESTQL

GET https://api.play.funql.io/sets?filter=eq(month(launchTime), 10)

POST https://api.play.funql.io/funql
Content-Type: text/plain

listSets(
  filter(
    eq(month(launchTime), 10)
  )
)

day¶

The day function has the following signature:

day(field: DateTime): Integer

The day function returns the day component of a DateTime parameter value. The day is given as an integer, ranging from 1 to 31.

For example:

set.json

{
  "name": "LEGO Star Wars Millennium Falcon",
  "setNumber": 75192,
  "price": 849.99,
  "launchTime": "2017-10-01T14:15:30.500Z"
}

day(launchTime)

Returns 1.

Usage

Return all sets that were launched on the 1st day of a month:

RESTQL

GET https://api.play.funql.io/sets?filter=eq(day(launchTime), 1)

POST https://api.play.funql.io/funql
Content-Type: text/plain

listSets(
  filter(
    eq(day(launchTime), 1)
  )
)

hour¶

The hour function has the following signature:

hour(field: DateTime): Integer

The hour function returns the hour component of a DateTime parameter value. The hour is given as an integer, ranging from 0 (12:00 A.M.) to 23 (11:00 P.M.).

For example:

set.json

{
  "name": "LEGO Star Wars Millennium Falcon",
  "setNumber": 75192,
  "price": 849.99,
  "launchTime": "2017-10-01T14:15:30.500Z"
}

hour(launchTime)

Returns 14.

Usage

Return all sets that were launched in the 14th hour of a day:

RESTQL

GET https://api.play.funql.io/sets?filter=eq(hour(launchTime), 14)

POST https://api.play.funql.io/funql
Content-Type: text/plain

listSets(
  filter(
    eq(hour(launchTime), 14)
  )
)

minute¶

The minute function has the following signature:

minute(field: DateTime): Integer

The minute function returns the minute component of a DateTime parameter value. The minute is given as an integer, ranging from 0 to 59.

For example:

set.json

{
  "name": "LEGO Star Wars Millennium Falcon",
  "setNumber": 75192,
  "price": 849.99,
  "launchTime": "2017-10-01T14:15:30.500Z"
}

minute(launchTime)

Returns 15.

Usage

Return all sets that were launched in the 15th minute of any hour on any day:

RESTQL

GET https://api.play.funql.io/sets?filter=eq(minute(launchTime), 15)

POST https://api.play.funql.io/funql
Content-Type: text/plain

listSets(
  filter(
    eq(minute(launchTime), 15)
  )
)

second¶

The second function has the following signature:

second(field: DateTime): Integer

The second function returns the second component of a DateTime parameter value. The second is given as an integer, ranging from 0 to 59.

For example:

set.json

{
  "name": "LEGO Star Wars Millennium Falcon",
  "setNumber": 75192,
  "price": 849.99,
  "launchTime": "2017-10-01T14:15:30.500Z"
}

second(launchTime)

Returns 30.

Usage

Return all sets that were launched in the 30th second of any minute of any hour on any day:

RESTQL

GET https://api.play.funql.io/sets?filter=eq(second(launchTime), 30)

POST https://api.play.funql.io/funql
Content-Type: text/plain

listSets(
  filter(
    eq(second(launchTime), 30)
  )
)

millisecond¶

The millisecond function has the following signature:

millisecond(field: DateTime): Integer

The millisecond function returns the millisecond component of a DateTime parameter value. The millisecond is given as an integer, ranging from 0 to 999.

For example:

set.json

{
  "name": "LEGO Star Wars Millennium Falcon",
  "setNumber": 75192,
  "price": 849.99,
  "launchTime": "2017-10-01T14:15:30.500Z"
}

millisecond(launchTime)

Returns 500.

Usage

Return all sets that were launched in the 500th millisecond of any second of any minute of any hour on any day:

RESTQL

GET https://api.play.funql.io/sets?filter=eq(millisecond(launchTime), 500)

POST https://api.play.funql.io/funql
Content-Type: text/plain

listSets(
  filter(
    eq(millisecond(launchTime), 500)
  )
)

Math functions¶

These functions round numerical values in different ways.

Function list¶

Name	Summary
`round`	Rounds a number to the nearest integer.
`floor`	Rounds a number down to the nearest integer.
`ceiling`	Rounds a number up to the nearest integer.

round¶

The round function has the following signature:

round(field: Float): Integer

The round function rounds the input parameter numeric value to the nearest numeric value with no decimal component.

FunQL uses away-from-zero rounding, meaning midpoint values (e.g., 0.5) are rounded to the next whole number away from zero. For example, 0.5 is rounded to 1 and ‑0.5 is rounded to -1.

For example:

set.json

{
  "name": "LEGO Star Wars Millennium Falcon",
  "setNumber": 75192,
  "price": 849.99,
  "launchTime": "2017-10-01T14:15:30.500Z"
}

round(price)

Returns 850.

Usage

Return all sets that have a price that rounds to 850:

RESTQL

GET https://api.play.funql.io/sets?filter=eq(round(price), 850)

POST https://api.play.funql.io/funql
Content-Type: text/plain

listSets(
  filter(
    eq(round(price), 850)
  )
)

floor¶

The floor function has the following signature:

floor(field: Float): Integer

The floor function rounds the input parameter numeric value down to the nearest numeric value with no decimal component.

For example:

set.json

{
  "name": "LEGO Star Wars Millennium Falcon",
  "setNumber": 75192,
  "price": 849.99,
  "launchTime": "2017-10-01T14:15:30.500Z"
}

floor(price)

Returns 849.

Usage

Return all sets that have a price that rounds down to 849:

RESTQL

GET https://api.play.funql.io/sets?filter=eq(floor(price), 849)

POST https://api.play.funql.io/funql
Content-Type: text/plain

listSets(
  filter(
    eq(floor(price), 849)
  )
)

ceiling¶

The ceiling function has the following signature:

ceiling(field: Float): Integer

The ceiling function rounds the input parameter numeric value up to the nearest numeric value with no decimal component.

For example:

set.json

{
  "name": "LEGO Star Wars Millennium Falcon",
  "setNumber": 75192,
  "price": 849.99,
  "launchTime": "2017-10-01T14:15:30.500Z"
}

ceiling(price)

Returns 850.

Usage

Return all sets that have a price that rounds up to 850:

RESTQL

GET https://api.play.funql.io/sets?filter=eq(ceiling(price), 850)

POST https://api.play.funql.io/funql
Content-Type: text/plain

listSets(
  filter(
    eq(ceiling(price), 850)
  )
)

String functions¶

These functions modify string values by changing their case.

Function list¶

Name	Summary
`lower`	Converts a string to lowercase.
`upper`	Converts a string to uppercase.

lower¶

The lower function has the following signature:

lower(field: String): String

The lower function returns the input parameter string value with all uppercase characters converted to lowercase according to Unicode rules.

For example:

set.json

{
  "name": "LEGO Star Wars Millennium Falcon",
  "setNumber": 75192,
  "price": 849.99,
  "launchTime": "2017-10-01T14:15:30.500Z"
}

lower(name)

Returns "lego star wars millennium falcon".

Usage

Return all sets that have a name that equals 'lego star wars millennium falcon' once any uppercase characters have been converted to lowercase:

RESTQL

GET https://api.play.funql.io/sets?filter=eq(lower(name), "lego star wars millennium falcon")

POST https://api.play.funql.io/funql
Content-Type: text/plain

listSets(
  filter(
    eq(lower(name), "lego star wars millennium falcon")
  )
)

upper¶

The upper function has the following signature:

upper(field: String): String

The upper function returns the input parameter string value with all lowercase characters converted to uppercase according to Unicode rules.

For example:

set.json

{
  "name": "LEGO Star Wars Millennium Falcon",
  "setNumber": 75192,
  "price": 849.99,
  "launchTime": "2017-10-01T14:15:30.500Z"
}

upper(name)

Returns "LEGO STAR WARS MILLENNIUM FALCON".

Usage

Return all sets that have a name that equals 'LEGO STAR WARS MILLENNIUM FALCON' once any lowercase characters have been converted to uppercase:

RESTQL

GET https://api.play.funql.io/sets?filter=eq(upper(name), "LEGO STAR WARS MILLENNIUM FALCON")

POST https://api.play.funql.io/funql
Content-Type: text/plain

listSets(
  filter(
    eq(upper(name), "LEGO STAR WARS MILLENNIUM FALCON")
  )
)