AdqlFunctionPrefixes < IVOA

IVOA Web>IvoaDAL>ADQL>AdqlFunctionPrefixes (2023-09-21, TamaraCivera) (raw view)
---++ ADQL function names

#FunctionNames

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 [[http://www.roe.ac.uk/ifa/wfau/][Wide Field Astronomy Unit (WFAU)]] use the department acronym, =wfau=, to prefix their user defined function names:

<verbatim>
    wfau_align()
    wfau_convert()</verbatim>

and the [[http://www.g-vo.org/pmwiki/][German Astrophysical Virtual Observatory (GAVO)]] adopt a similar naming convention:

<verbatim>
    gavo_align()
    gavo_convert()</verbatim>

this would help to avoid confusion when users encounter functions with similar names on different TAP services:
<verbatim>
    wfau_align()
    gavo_align()

    wfau_convert()
    gavo_convert()</verbatim>

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.

<verbatim>
    wfau_align()</verbatim>

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

#StandardNames

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.

<verbatim>
    ivo_align()</verbatim>

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

<verbatim>
    gavo_align()  -- original GAVO version
    ivo_align()   -- IVOA standard version</verbatim>

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

<verbatim>
    gavo_align()  -- original GAVO version
    wfau_align()  -- alternative WFAU version
    ivo_align()  -- IVOA standard  version</verbatim>

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 [[http://ivoa.net/documents/TAPRegExt/index.html][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 [[http://ivoa.net/documents/RegTAP][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

#PrefixRegistry

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/ |
| cefca | Centro de Estudios de Física del Cosmos de Aragón (CEFCA) | https://archive.cefca.es/ |
If you would like to to participate, please add your prefix to the table.

---+++ Next steps

#NextSteps

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 -- IVOA.DaveMorris with additions and suggestions from -- IVOA.MarkusDemleitner

<!--
      * Set ALLOWTOPICRENAME = IVOA.TWikiAdminGroup
-->
Topic revision: r6 - 2023-09-21 - TamaraCivera
IVOA
Log in or Register
IVOA.net
Wiki Home
WebChanges
WebTopicList
WebStatistics
Twiki Meta & Help
IVOA
Know
Main
Sandbox
TWiki
TWiki intro
TWiki tutorial
User registration
Notify me
Working Groups
Interest Groups
Time Domain
Committees
Stds&Procs
www.ivoa.net
Documents
Events
Members
XML Schema