[jira] [Created] (DRILL-7309) Improve documentation for table functions

["Paul Rogers (JIRA)" <ji...@apache.org>]

Paul Rogers created DRILL-7309:
----------------------------------

             Summary: Improve documentation for table functions
                 Key: DRILL-7309
                 URL: https://issues.apache.org/jira/browse/DRILL-7309
             Project: Apache Drill
          Issue Type: Bug
          Components: Documentation
    Affects Versions: 1.16.0
            Reporter: Paul Rogers
            Assignee: Bridget Bevens


Consider the [documentation of table functions|https://drill.apache.org/docs/plugin-configuration-basics/], 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|https://drill.apache.org/docs/query-directory-functions/]. 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)'''
```



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)