Query for UDFs

You can include User Defined Fields, such as ranges and quantiles, in your table query by:

Adding a udfs section; use this to define the structure of the UDF.
Adding your UDF to the dimensions.

For more details about range and quantile UDFs, see Ranges and Quantiles.

Range UDFs

Following is an example of a table query that defines a range UDF:

CODE

{
  "database" : "str:database:bank",
  "measures" : [ "str:count:bank:F_Customer" ],
  "udfs": {
		"myRange":{
    		"type": "RANGE",
    		"from": 1,
    		"to": 500,
    		"increment": 100,
    		"measure": "str:measure:bank:F_Customer:Cust_Profit",
    		"label": "My Range",
    		"toInclusive": true
		}		
	},
  "dimensions" : [                  
        [ "str:field:bank:F_Customer:Gender" ], [ "str:udf:myRange" ]
  ]
}

Where:

myRange

This is an ID for the UDF; you can replace it with any string.

You need to use this ID in the dimensions section to add the UDF to the query in the form str:udf:<ID>. In the example above, the ID has been set to myRange so the dimensions section needs to include str:udf:myRange.

type

Set to RANGE for a range UDF.

from

The starting value for the set of ranges.

to

The end value for the set of ranges.

increment

The size of each range.

measure

The Open Data ID of the measure you want to create a range for. This needs to match the ID format this is returned by the /schema endpoint.

label

A label (display name) for the UDF that will be returned in the query results.

toInclusive

Set this to either true or false. It indicates how the upper boundary of each range is included. For example the above configuration would create the following range buckets, depending on the value of toInclusive:

true	false
1 or less	Less than 1
More than 1 to 101	1 to less than 101
More than 101 to 201	101 to less than 201
More than 201 to 301	201 to less than 301
More than 301 to 401	301 to less than 401
More than 401	401 or more

Quantile UDFs

Following is an example of a table query that defines a quantile UDF:

CODE

{
  "database" : "str:database:bank",
  "measures" : [ "str:count:bank:F_Customer" ],
	  "udfs": {
		"myRange": { 
    		"type": "QUANTILE",
    		"label": "My Quantile",
    		"measure": "str:measure:bank:F_Customer:Cust_Profit",
    		"distribution": "str:count:bank:F_Customer",
    		"ranges": 5
		}		
	},
  "dimensions" : [                  
        [ "str:field:bank:F_Customer:Gender" ], [ "str:udf:myRange" ]
  ]
}

Where:

myRange	This is an ID for the UDF; you can replace it with any string. You need to use this ID in the `dimensions` section to add the UDF to the query in the form `str:udf:<ID>`. In the example above, the ID has been set to `myRange` so the `dimensions` section needs to include `str:udf:myRange`.
type	Set to `QUANTILE` for a quantile UDF.
label	A label (display name) for the UDF that will be returned in the query results.
measure	The Open Data ID of the measure you want to create a quantile for. This needs to match the ID format this is returned by the `/schema` endpoint.
distribution	The measure or count to use to determine the distribution of the quantile. This can be any measure or count, but must return positive values for all records. It is equivalent to the Equal Distribution Of setting in SuperWEB2. See Ranges and Quantiles for more details.
ranges	The number of quantile ranges to create. By default you can choose between 2 and 10, but these limits can be configured by the administrator on a per-dataset basis using the SuperADMIN `ranges` command.