Functions

A function is invoked in a query request in exactly the same way as any other collection - recall that a function is simply a collection which returns a single row, and a single column, named __value.

Because a function returns a single row, many query capabilities are limited in their usefulness:

• It would not make sense to specify limit or offset,
• Sorting has no effect
• Filtering can only remove the whole result row, based on some condition expressed in terms of the result.

However, some query functions are still useful in the context of functions:

• The caller can request a subset of the full result, by using nested field queries,
• A function can be the source or target of a relationship,
• Function arguments are specified in the same way as collection arguments, and can also be specified using variables.

Examples

A function returning a scalar value

This example uses the latest_article_id function, which returns a scalar type:

{
    "arguments": {},
    "query": {
        "fields": {
            "__value": {
                "type": "column",
                "column": "__value"
            }
        }
    },
    "collection_relationships": {}
}

The response JSON includes the requested data in the special __value field:

[
  {
    "rows": [
      {
        "__value": 3
      }
    ]
  }
]

A function returning an object type

This example uses the latest_article function instead, which returns the full article object. To query the object structure, it uses a nested field request:

{
    "arguments": {},
    "query": {
        "fields": {
            "__value": {
                "type": "column",
                "column": "__value",
                "fields": {
                    "type": "object",
                    "fields": {
                        "id": {
                            "type": "column",
                            "column": "id"
                        },
                        "title": {
                            "type": "column",
                            "column": "title"
                        }
                    }
                }
            }
        }
    },
    "collection_relationships": {}
}

Again, the response is sent in the __value field:

[
  {
    "rows": [
      {
        "__value": {
          "id": 3,
          "title": "The Design And Implementation Of Programming Languages"
        }
      }
    ]
  }
]