Uploaded image for project: 'Apache Drill'
  1. Apache Drill
  2. DRILL-7309

Improve documentation for table functions

    XMLWordPrintableJSON

    Details

    • Type: Bug
    • Status: Open
    • Priority: Minor
    • Resolution: Unresolved
    • Affects Version/s: 1.16.0
    • Fix Version/s: None
    • Component/s: Documentation
    • Labels:
      None

      Description

      Consider the documentation of table functions, the "Using the Formats Attributes as Table Function Parameters" section. The documentation is a bit sparse and it always takes me a long time to remember how to use table functions. Here are some improvements.

      > ...use the table function syntax:

      > select a, b from table(

      {table function name}

      (parameters))

      > The table function name is the table name, the type parameter is the format name, ...

      Change the second line to:

      ```
      select a, b from table(<table name>(type='<format-name>', <parameters>))
      ```

      The use of the angle brackets is a bit more consistent with other doc pages such as this one. We already mentioned the type parameter, but did not show it in the template. Then say:

      The type parameter must match the name of a format plugin. This is the name you put in the type field of your plugin JSON as explained above. Note that this is not the name of your format config. That is, it might be "text", not "csv" or "csvh".

      The type parameter must be the first parameter. Other parameters can appear in any order. You must provide required parameters. Only string, Boolean and integer parameters are supported. Table functions do not support lists (so you cannot specify the extensions, for example.)

      If parameter names are the same as SQL reserved words, quote the parameter with back-ticks as for table and column names. Quote string values with single-quotes. Do not quote integer values.

      If the string value contains back-slashes, you must escape them with a second back-slash. If the string contains a single-quote, you must escape it with another single-quote. Example:

      ```
      `regex` => '''(
      d)'''
      ```

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                bbevens Bridget Bevens
                Reporter:
                Paul.Rogers Paul Rogers
              • Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated: