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:

{
  "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 lessLess than 1
More than 1 to 1011 to less than 101
More than 101 to 201101 to less than 201
More than 201 to 301201 to less than 301
More than 301 to 401301 to less than 401
More than 401401 or more


Quantile UDFs

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

{
  "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.