ADQL function names

The ADQL standard itself does not impose any restrictions on the names that may be used for user defined functions.

To avoid name collisions when solving common problems, we recommend that TAP service providers adopt a policy of consistently prefixing the names of user-defined functions provided by their services with an acronym that represents the institute, department or archive where the function originates.

If the Wide Field Astronomy Unit (WFAU) use the department acronym, wfau, to prefix their user defined function names:

    wfau_align()
    wfau_convert()

and the German Astrophysical Virtual Observatory (GAVO) adopt a similar naming convention:

    gavo_align()
    gavo_convert()

this would help to avoid confusion when users encounter functions with similar names on different TAP services:

    wfau_align()
    gavo_align()

    wfau_convert()
    gavo_convert()

Note that the prefix indicates the origin of the function implementation, not the identity of the TAP service providing the function. If another TAP service provides a function with exactly the same behaviour as one of the WFAU functions, the function name should use the wfau prefix to indicate this.

    wfau_align()

By ensuring that different implementations use different names, this scheme avoids potential conflicts when a user takes a query written for one TAP service and sends it to another TAP service. With the name prefixes, the second TAP service will reject the query if it does not provide exactly the same function as the first.

Without this fail fast approach, the second query may run without raising any errors or warnings, but due to differences in the algorithm used, the second query may produce subtly different results which could go undetected.

On the other hand, if the second TAP service does implement the same function, with exactly the same behaviour, then selecting this function using the name prefix gives the user a level of confidence that a query would produce equivalent results when run on different TAP services.

IVO standard functions

The ivo prefix is reserved for defining functions that are specified in IVOA recommendations or endorsed notes.

If one of the GAVO functions is adopted as part of an IVOA standard, then we could use the ivo prefix to indicate that it is an IVOA standard function.

    ivo_align()

For backwards compatibility, a TAP services could provide the same function using different names:

    gavo_align()  -- original GAVO version
    ivo_align()   -- IVOA standard version

The same TAP service could also provide the WFAU implementation of the same function:

    gavo_align()  -- original GAVO version
    wfau_align()  -- alternative WFAU version
    ivo_align()  -- IVOA standard  version

It is the responsibility of the IVOA working groups to ensure that the total set of ivo endorsed functions remains sensible.

In order to be accepted as an ivo function, a function MUST be defined in a format suitable for TAPRegExt and ideally have reference implementations for one or more of the major RDMS platforms.

Note that in general a TAP service is not required to implement these functions. However, if they do implement functions with these names, then their implementation MUST be consistent with the behaviour defined in the specification.

An example for a Recommendation that defines ivo functions is RegTAP, which defines the following functions:

  • ivo_nocasematch case insensitive match.
  • ivo_hasword word based search.
  • ivo_hashlist_has hash '#' delimited word search.
  • ivo_string_agg delimited string aggregate function.

Prefix registry

The following table acts as an informal registry of function prefix names.

prefix name link
ivo IVOA standard functions http://ivoa.net/
wfau Wide Field Astronomy Unit, Institute for Astronomy, University of Edinburgh http://www.roe.ac.uk/ifa/wfau/
gavo German Astrophysical Virtual Observatory http://www.g-vo.org/pmwiki/
mast Mikulski Archive for Space Telescopes http://archive.stsci.edu/
eso European Southern Observatory http://archive.eso.org/

If you would like to to participate, please add your prefix to the table.

Next steps

If you are adding new user defined functions to your TAP services, consider adding a prefix to the function name to indicate where the function comes from.

If you already have user defined functions in your TAP services, introduce alternative names for them with an appropriate prefix and gradually encourage your users to use the prefixed names.


Original text by -- DaveMorris with additions and suggestions from -- MarkusDemleitner

Topic revision: r5 - 2017-04-19 - AlbertoMicol
 
This site is powered by the TWiki collaboration platformCopyright © 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback