Skip to content

Commit cc9c8d9

Browse files
aalva500-progaaarone90
aalva500-prog
and
aaarone90
authored
Updating documentation for fields and table commands (opensearch-project#4177)
* Fixing documentation for fields and table commands Signed-off-by: Aaron Alvarez <aaarone@amazon.com> * Addressing Tomo's comments Signed-off-by: Aaron Alvarez <aaarone@amazon.com> * Update category.json Signed-off-by: Aaron Alvarez <900908alvarezaaron@gmail.com> --------- Signed-off-by: Aaron Alvarez <aaarone@amazon.com> Signed-off-by: Aaron Alvarez <900908alvarezaaron@gmail.com> Co-authored-by: Aaron Alvarez <aaarone@amazon.com>
1 parent 9b88f23 commit cc9c8d9

5 files changed

Lines changed: 232 additions & 174 deletions

File tree

‎docs/category.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,6 @@
1414
"user/ppl/cmd/showdatasources.rst",
1515
"user/ppl/cmd/information_schema.rst",
1616
"user/ppl/cmd/eval.rst",
17-
"user/ppl/cmd/fields.rst",
1817
"user/ppl/cmd/fillnull.rst",
1918
"user/ppl/cmd/grok.rst",
2019
"user/ppl/cmd/head.rst",
@@ -57,6 +56,8 @@
5756
"user/dql/metadata.rst"
5857
],
5958
"ppl_cli_calcite": [
59+
"user/ppl/cmd/stats.rst",
60+
"user/ppl/cmd/fields.rst",
6061
"user/ppl/cmd/regex.rst",
6162
"user/ppl/cmd/stats.rst"
6263
]

‎docs/user/ppl/cmd/fields-enhanced.rst‎

Lines changed: 0 additions & 169 deletions
This file was deleted.

‎docs/user/ppl/cmd/fields.rst‎

Lines changed: 165 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,7 @@ Description
1313
============
1414
Using ``field`` command to keep or remove fields from the search result.
1515

16-
.. note::
17-
Enhanced field features are available when the Calcite engine is enabled. For detailed documentation on enhanced features, see `fields-enhanced <fields-enhanced.rst>`_
16+
Enhanced field features are available when the Calcite engine is enabled with 3.3+ version. When Calcite is disabled, only basic comma-delimited field selection is supported.
1817

1918
Syntax
2019
============
@@ -24,8 +23,11 @@ field [+|-] <field-list>
2423
* field list: mandatory. comma-delimited keep or remove fields.
2524

2625

26+
Basic Examples
27+
==============
28+
2729
Example 1: Select specified fields from result
28-
==============================================
30+
----------------------------------------------
2931

3032
The example show fetch account_number, firstname and lastname fields from search results.
3133

@@ -43,7 +45,7 @@ PPL query::
4345
+----------------+-----------+----------+
4446

4547
Example 2: Remove specified fields from result
46-
==============================================
48+
----------------------------------------------
4749

4850
The example show fetch remove account_number field from search results.
4951

@@ -59,3 +61,162 @@ PPL query::
5961
| Nanette | Bates |
6062
| Dale | Adams |
6163
+-----------+----------+
64+
65+
Enhanced Features (Version 3.3.0)
66+
===========================================
67+
68+
All features in this section require the Calcite engine to be enabled. When Calcite is disabled, only basic comma-delimited field selection is supported.
69+
70+
Example 3: Space-delimited field selection
71+
-------------------------------------------
72+
73+
Fields can be specified using spaces instead of commas, providing a more concise syntax.
74+
75+
**Syntax**: ``fields field1 field2 field3``
76+
77+
PPL query::
78+
79+
os> source=accounts | fields firstname lastname age;
80+
fetched rows / total rows = 4/4
81+
+-----------+----------+-----+
82+
| firstname | lastname | age |
83+
|-----------+----------+-----|
84+
| Amber | Duke | 32 |
85+
| Hattie | Bond | 36 |
86+
| Nanette | Bates | 28 |
87+
| Dale | Adams | 33 |
88+
+-----------+----------+-----+
89+
90+
Example 4: Prefix wildcard pattern
91+
-----------------------------------
92+
93+
Select fields starting with a pattern using prefix wildcards.
94+
95+
PPL query::
96+
97+
os> source=accounts | fields account*;
98+
fetched rows / total rows = 4/4
99+
+----------------+
100+
| account_number |
101+
|----------------|
102+
| 1 |
103+
| 6 |
104+
| 13 |
105+
| 18 |
106+
+----------------+
107+
108+
Example 5: Suffix wildcard pattern
109+
-----------------------------------
110+
111+
Select fields ending with a pattern using suffix wildcards.
112+
113+
PPL query::
114+
115+
os> source=accounts | fields *name;
116+
fetched rows / total rows = 4/4
117+
+-----------+----------+
118+
| firstname | lastname |
119+
|-----------+----------|
120+
| Amber | Duke |
121+
| Hattie | Bond |
122+
| Nanette | Bates |
123+
| Dale | Adams |
124+
+-----------+----------+
125+
126+
Example 6: Contains wildcard pattern
127+
------------------------------------
128+
129+
Select fields containing a pattern using contains wildcards.
130+
131+
PPL query::
132+
133+
os> source=accounts | fields *a* | head 1;
134+
fetched rows / total rows = 1/1
135+
+----------------+-----------+-----------------+---------+-------+-----+----------------------+----------+
136+
| account_number | firstname | address | balance | state | age | email | lastname |
137+
|----------------+-----------+-----------------+---------+-------+-----+----------------------+----------|
138+
| 1 | Amber | 880 Holmes Lane | 39225 | IL | 32 | amberduke@pyrami.com | Duke |
139+
+----------------+-----------+-----------------+---------+-------+-----+----------------------+----------+
140+
141+
Example 7: Mixed delimiter syntax
142+
----------------------------------
143+
144+
Combine spaces and commas for flexible field specification.
145+
146+
PPL query::
147+
148+
os> source=accounts | fields firstname, account* *name;
149+
fetched rows / total rows = 4/4
150+
+-----------+----------------+----------+
151+
| firstname | account_number | lastname |
152+
|-----------+----------------+----------|
153+
| Amber | 1 | Duke |
154+
| Hattie | 6 | Bond |
155+
| Nanette | 13 | Bates |
156+
| Dale | 18 | Adams |
157+
+-----------+----------------+----------+
158+
159+
Example 8: Field deduplication
160+
-------------------------------
161+
162+
Automatically prevents duplicate columns when wildcards expand to already specified fields.
163+
164+
PPL query::
165+
166+
os> source=accounts | fields firstname, *name;
167+
fetched rows / total rows = 4/4
168+
+-----------+----------+
169+
| firstname | lastname |
170+
|-----------+----------|
171+
| Amber | Duke |
172+
| Hattie | Bond |
173+
| Nanette | Bates |
174+
| Dale | Adams |
175+
+-----------+----------+
176+
177+
Note: Even though ``firstname`` is explicitly specified and would also match ``*name``, it appears only once due to automatic deduplication.
178+
179+
Example 9: Full wildcard selection
180+
-----------------------------------
181+
182+
Select all available fields using ``*`` or ```*```. This selects all fields defined in the index schema, including fields that may contain null values.
183+
184+
PPL query::
185+
186+
os> source=accounts | fields `*` | head 1;
187+
fetched rows / total rows = 1/1
188+
+----------------+-----------+-----------------+---------+--------+--------+----------+-------+-----+----------------------+----------+
189+
| account_number | firstname | address | balance | gender | city | employer | state | age | email | lastname |
190+
|----------------+-----------+-----------------+---------+--------+--------+----------+-------+-----+----------------------+----------|
191+
| 1 | Amber | 880 Holmes Lane | 39225 | M | Brogan | Pyrami | IL | 32 | amberduke@pyrami.com | Duke |
192+
+----------------+-----------+-----------------+---------+--------+--------+----------+-------+-----+----------------------+----------+
193+
194+
Note: The ``*`` wildcard selects fields based on the index schema, not on data content. Fields with null values are included in the result set. Use backticks ```*``` if the plain ``*`` doesn't return all expected fields.
195+
196+
Example 10: Wildcard exclusion
197+
-------------------------------
198+
199+
Remove fields using wildcard patterns with the minus (-) operator.
200+
201+
PPL query::
202+
203+
os> source=accounts | fields - *name;
204+
fetched rows / total rows = 4/4
205+
+----------------+----------------------+---------+--------+--------+----------+-------+-----+-----------------------+
206+
| account_number | address | balance | gender | city | employer | state | age | email |
207+
|----------------+----------------------+---------+--------+--------+----------+-------+-----+-----------------------|
208+
| 1 | 880 Holmes Lane | 39225 | M | Brogan | Pyrami | IL | 32 | amberduke@pyrami.com |
209+
| 6 | 671 Bristol Street | 5686 | M | Dante | Netagy | TN | 36 | hattiebond@netagy.com |
210+
| 13 | 789 Madison Street | 32838 | F | Nogal | Quility | VA | 28 | null |
211+
| 18 | 467 Hutchinson Court | 4180 | M | Orick | null | MD | 33 | daleadams@boink.com |
212+
+----------------+----------------------+---------+--------+--------+----------+-------+-----+-----------------------+
213+
214+
Requirements
215+
============
216+
- **Calcite Engine**: All enhanced features require the Calcite engine to be enabled
217+
- **Backward Compatibility**: Basic comma-delimited syntax continues to work when Calcite is disabled
218+
- **Error Handling**: Attempting to use enhanced features without Calcite will result in an ``UnsupportedOperationException``
219+
220+
See Also
221+
========
222+
- `table <table.rst>`_ - Alias command with identical functionality

0 commit comments

Comments
 (0)