RequestedColumn (Drill : 1.20.3 API)

All Known Implementing Classes:: BaseRequestedColumn, RequestedColumnImpl, RequestedWildcardColumn

public interface RequestedColumn

Plan-time properties of a requested column. Represents a consolidated view of the set of references to a column. For example, the project list might contain:

SELECT *
SELECT filename, *, dir0
SELECT a, b, c
SELECT columns[4], columns[8]
SELECT a.b, a.c
SELECT columns, columns[1]
SELECT a, a.b

In each case, the same column is referenced in different forms which are consolidated into this abstraction.

The resulting information is a "pattern": a form of reference. Given the requested column, code can check if some concrete reader-provided column is consistent with the requested projection or not. The project list does not contain sufficient information to definitively pick a type; it only excludes certain types.

Even for complex types, we cannot definitively know the type. For example, the projection a[0] could either refer to an array (of any type), or a DICT with integer keys. Similarly, a projection of the form a.b can either refer to a member of a map, or the "b" string key of a DICT column.

Compatibility Rules

The pattern given by projection is consistent with certain concrete types as follows. + means any number of additional qualifiers. Note that the following list is conceptual based on observed practice; the actual implementation may be more restrictive.

Type	Consistent with
Non-repeated MAP	`a`, `a.b`
Repeated MAP	`a`, `a.b`, `a[n].b`
Non-repeated Scalar	`a`
Repeated Scalar	`a`, `a[n]`
Non-repeated DICT	`a`, `a[n]`, `a['key']`
Repeated DICT	`a`, `a[n]`, `a['key']`, `a[n][m]`, `a[n]['key']`
Non-repeated LIST	`a`, `a[n]`
Repeated LIST	`a`, `a[n]`, `a[n][n]`

MAP, DICT, UNION and LIST are structured types: projection can reach into the structure to any number of levels. In such a case, when sufficient schema information is available, the above rules can be applied recursively to each level of structure. The recursion can be done in the class for a DICT (since there is only one child type), but must be external for other complex types. For MAP, the column can report which specific members are projected.

The Text reader allows the columns column, which allows the user to specify indexes. This class reports which indexes were actually selected. Index information is available only at the top level, but not for 2+ dimensions.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`int`	`arrayDims()` If `isArray()` returns true, reports the number of dimensions observed in projection.
`String`	`fullName()` Returns the fully-qualified column name.
`boolean`	`hasIndex(int index)` Report is a specific index was selected.
`boolean`	`hasIndexes()` Reports if the projection list included (only) specific element indexes.
`boolean[]`	`indexes()` Return a bitmap of the selected indexes.
`boolean`	`isArray()` Report whether the first qualifier is an array.
`boolean`	`isSimple()`
`boolean`	`isTuple()` Report whether the projection implies a tuple.
`boolean`	`isWildcard()` Several consumers of this this mechanism process the "raw" projection list which can contain a combination of wildcard and otehr columns.
`int`	`maxIndex()` Return the maximum index value, if only explicit indexes were given.
`String`	`name()` The column name as projected.
`boolean`	`nameEquals(String target)` Case-insensitive comparison of the column name.
`Qualifier`	`qualifier()` The internal qualifier information for the column.
`RequestedTuple`	`tuple()` Return projection information for the column as a tuple.

- Method Detail
  - name
```
String name()
```
    The column name as projected. If the same column appears multiple times (as in a[1], A[2], then the case of the first appearance is used.
    
    Returns:
    
    the column name as observed in the project list
  - fullName
```
String fullName()
```
    Returns the fully-qualified column name. If the column is in the top-level tuple, this is the same as name(). If the column is nested in an array, then this name includes the enclosing columns: a.b.c.
    
    Returns:
    
    the full name with enclosing map prefixes, if any
  - nameEquals
```
boolean nameEquals(String target)
```
    Case-insensitive comparison of the column name.
  - isWildcard
```
boolean isWildcard()
```
    Several consumers of this this mechanism process the "raw" projection list which can contain a combination of wildcard and otehr columns. For example: filename, *, dir0. The requested tuple preserves the wildcard within the projection list so that, say, the projection mechanism can insert the actual data columns between the two implicit columns in the example.
    If a column is a wildcard, then none of the other methods apply, since this projected column represents any number or actual columns.
    
    Returns:
    
    if this column is the wildcard placeholder
  - isSimple
```
boolean isSimple()
```
    Returns:
    
    true if this column has no qualifiers. Example: a.
  - isTuple
```
boolean isTuple()
```
    Report whether the projection implies a tuple. Example: a.b. Not that this method, and others can only tell if the projection implies a tuple; the actual column may be a tuple (MAP), but be projected simply. The map format also describes a DICT with a VARCHAR key.
    
    Returns:
    
    true if the column has a map-like projection.
  - tuple
```
RequestedTuple tuple()
```
    Return projection information for the column as a tuple. If projection included references to nested columns (such as a.b, a.c, then the tuple projection will list only the referenced columns. However, if projection is generic (m), then we presume all columns of the map are projected and the returned object assumes all members are projected.
    
    Returns:
    
    projection information for a (presumed) map column
  - isArray
```
boolean isArray()
```
    Report whether the first qualifier is an array. Example: a[1]. The array format also describes a DICT with an integer key.
    
    Returns:
    
    true if the column must be an array.
  - arrayDims
```
int arrayDims()
```
    If isArray() returns true, reports the number of dimensions observed in projection. That is if projection is a[0][1], then this method returns 2.
    Note that, as with all projection-level information, this number reflects only what was in the project list; not what might be the number of dimensions in the actual input source.
    
    Returns:
    
    the maximum number of array dimensions observed in the projection list, or 0 if this column was not observed to be an array (if isArray() returns false.
  - hasIndexes
```
boolean hasIndexes()
```
    Reports if the projection list included (only) specific element indexes. For example: a[2], a[5]. The user could also project both indexes and the array: a[0], a. In this case isArray() is {code true}, but hasIndexes() is false.
    
    Returns:
    
    true if the column has enumerated indexes, false if the column was also projected as a whole, or if this column was not observed to be an array
  - maxIndex
```
int maxIndex()
```
    Return the maximum index value, if only explicit indexes were given. Valid if hasIndexes() returns true.
    
    Returns:
    
    the maximum array index value known to the projection, or 0 if isArray() is false. Also returns 0 if hasIndexe() returns false, meaning that either the column was not observed to be an array, or was projected with both indexes and by itself: a[0], a.
  - indexes
```
boolean[] indexes()
```
    Return a bitmap of the selected indexes. Only valid if hasIndexes() returns true.
    
    Returns:
    
    a bitmap of the selected array indexes, or null if hasIndexes() returns false.
  - hasIndex
```
boolean hasIndex(int index)
```
    Report is a specific index was selected. Short cut for the other array methods. Used in cases such as the columns column where the user can select specific elements (column) but not others.
    
    Parameters:
    
    index - the array index to check
    
    Returns:
    
    true if the array element was projected, either explicitly (a[3]) or implicitly (a). Returns false only if hasIndexes() returns true (the user listed only explicit indexes) and the requested index is not among those requested (index >= maxIndex() || !indexes()[index])
  - qualifier
```
Qualifier qualifier()
```
    The internal qualifier information for the column. Generally not needed by clients; use the other informations to interpret the qualifier for you.
    
    Returns:
    
    detailed column qualifier information, if the column was seen to be complex in the project list

Interface RequestedColumn

Compatibility Rules

Method Summary

Method Detail

name

fullName

nameEquals

isWildcard

isSimple

isTuple

tuple

isArray

arrayDims

hasIndexes

maxIndex

indexes

hasIndex

qualifier