You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@geode.apache.org by db...@apache.org on 2018/03/08 23:38:37 UTC
[geode] branch develop updated: GEODE-4795: User Guide: Inequality
queries return UNDEFINED entries
This is an automated email from the ASF dual-hosted git repository.
dbarnes pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/geode.git
The following commit(s) were added to refs/heads/develop by this push:
new 3dfad34 GEODE-4795: User Guide: Inequality queries return UNDEFINED entries
3dfad34 is described below
commit 3dfad345f292a3e71498d922c16372655ace49c6
Author: Dave Barnes <db...@pivotal.io>
AuthorDate: Wed Mar 7 11:17:10 2018 -0800
GEODE-4795: User Guide: Inequality queries return UNDEFINED entries
---
.../query_additional/literals.html.md.erb | 24 ++++++++++++---
.../query_additional/operators.html.md.erb | 36 +++++++++++++---------
.../supported_keywords.html.md.erb | 8 ++---
.../query_select/the_select_statement.html.md.erb | 4 +--
4 files changed, 47 insertions(+), 25 deletions(-)
diff --git a/geode-docs/developing/query_additional/literals.html.md.erb b/geode-docs/developing/query_additional/literals.html.md.erb
index 40c4434..8b7317e 100644
--- a/geode-docs/developing/query_additional/literals.html.md.erb
+++ b/geode-docs/developing/query_additional/literals.html.md.erb
@@ -19,8 +19,6 @@ See the License for the specific language governing permissions and
limitations under the License.
-->
-## <a id="literals__section_BA2D0AC444EB45088F00D9E2C8A1DD06" class="no-quick-link"></a>Comparing Values With java.util.Date
-
<%=vars.product_name%> supports the following literal types:
<dt>**boolean**</dt>
@@ -44,8 +42,26 @@ limitations under the License.
<dd>Equivalent alternative of `NULL`.</dd>
<dt>**NULL**</dt>
<dd>The same as `null` in Java.</dd>
-<dt>**UNDEFINED**</dt>
-<dd>A special literal that is a valid value for any data type. An `UNDEFINED` value is the result of accessing an attribute of a null-valued attribute. Note that if you access an attribute that has an explicit value of null, then it is not undefined. For example if a query accesses the attribute address.city and address is null, the result is undefined. If the query accesses address, then the result is not undefined, it is `NULL`.</dd>
+<a id="literals__section_undefined" class="no-quick-link"></a><dt>**UNDEFINED**</dt>
+<dd>A special literal, valid value for any data type, indicating that no value (not even NULL) has been designated for a given data item.</dd>
+
+## The Difference Between NULL and UNDEFINED
+
+In OQL, as in Java, NULL is an assignable entity (an object) indicating "no value".
+
+In OQL, UNDEFINED is a type. There is no Java equivalent. In OQL search results, an UNDEFINED value can be returned in two cases:
+
+- As the result of a search for a key or value that does not exist
+- As the result of accessing an attribute of a null-valued attribute.
+
+Searches for inequality return UNDEFINED values in their results.
+
+Note that if you access an attribute that has an explicit value of NULL, then it is not UNDEFINED.
+
+For example, if a query accesses the attribute `address.city` and `address` is NULL, the result is UNDEFINED.
+If the query accesses `address`, then the result is not UNDEFINED, it is NULL.
+
+## <a id="literals__section_BA2D0AC444EB45088F00D9E2C8A1DD06" class="no-quick-link"></a>Comparing Values With java.util.Date
You can compare temporal literal values `DATE`, `TIME`, and `TIMESTAMP` with `java.util.Date` values. There is no literal for `java.util.Date` in the query language.
diff --git a/geode-docs/developing/query_additional/operators.html.md.erb b/geode-docs/developing/query_additional/operators.html.md.erb
index 352e0a3..8d3d924 100644
--- a/geode-docs/developing/query_additional/operators.html.md.erb
+++ b/geode-docs/developing/query_additional/operators.html.md.erb
@@ -27,17 +27,23 @@ Comparison operators compare two values and return the results, either TRUE or F
The following are supported comparison operators:
-| | |
+| Operator | Meaning |
|----------|--------------------------|
-| = | equal to |
-| <> | not equal to |
-| != | not equal to |
| < | less than |
| <= | less than or equal to |
| > | greater than |
| >= | greater than or equal to |
+| | |
+| = | equal to |
+| != | not equal to |
+| <> | not equal to |
-The equal and not equal operators have lower precedence than the other comparison operators. They can be used with null. To perform equality or inequality comparisons with UNDEFINED, use the IS\_DEFINED and IS\_UNDEFINED preset query functions instead of these comparison operators.
+Regarding equality and inequality operators:
+
+- The equality and inequality operators have lower precedence than the other comparison operators.
+- The equality and inequality operators can be used with null.
+- Inequality queries return results for which the search field is [UNDEFINED](literals.html#literals__section_undefined).
+- To perform equality or inequality comparisons with [UNDEFINED](literals.html#literals__section_undefined), use the IS\_DEFINED and IS\_UNDEFINED preset query functions instead of these comparison operators.
## <a id="operators__section_6A85A9DDA47E47009FDE1CC38D7BA66C" class="no-quick-link"></a>Logical Operators
@@ -45,7 +51,7 @@ The logical operators AND and OR allow you to create more complex expressions by
## <a id="operators__section_A970AE75B0D24E0B9E1B61BE2D9842D8" class="no-quick-link"></a>Unary Operators
-Unary operators operate on a single value or expression, and have lower precedence than comparison operators in expressions. <%=vars.product_name%> supports the unary operator NOT. NOT is the negation operator, which changes the value of the operand to its opposite. So if an expression evaluates to TRUE, NOT changes it to FALSE. The operand must be a boolean.
+Unary operators operate on a single value or expression, and have lower precedence than comparison operators in expressions. <%=vars.product_name%> supports the unary operator NOT. NOT is the negation operator, which changes the value of the operand to its opposite. For example, if an expression evaluates to TRUE, NOT changes it to FALSE. The operand must be a boolean.
## <a id="operators_arithmetic_OQL" class="no-quick-link"></a>Arithmetic Operators
@@ -57,20 +63,20 @@ and `getCause()` will state `ArithmeticException`.
The following are supported arithmetic operators:
-| | |
-|---------|--------------------------|
-| + | addition |
-| - | subtraction |
-| * | multiplication |
-| / | division |
-| % | modulus |
-| MOD | modulus |
+| Operator | Meaning |
+|----------|--------------------------|
+| + | addition |
+| - | subtraction |
+| * | multiplication |
+| / | division |
+| % | modulus |
+| MOD | modulus |
## <a id="operators__section_E78FB4FB3703471C8186A0E26D25F01F" class="no-quick-link"></a>Map and Index Operators
Map and index operators access elements in key/value collections (such as maps and regions) and ordered collections (such as arrays, lists, and `String`s). The operator is represented by a set of square brackets (`[ ]`) immediately following the name of the collection. The mapping or indexing specification is provided inside these brackets.
-Array, list, and `String` elements are accessed using an index value. Indexing starts from zero for the first element, 1 for the second element and so on. If `myList` is an array, list, or String and `index` is an expression that evaluates to a non-negative integer, then `myList[index]` represents the (`index + 1`)th element of `myList`. The elements of a `String` are the list of characters that make up the string.
+Array, list, and `String` elements are accessed using an index value. Indexing starts from zero for the first element, 1 for the second element, and so on. If `myList` is an array, list, or `String` and `index` is an expression that evaluates to a non-negative integer, then `myList[index]` represents the (`index + 1`)th element of `myList`. The elements of a `String` are the list of characters that make up the string.
Map and region values are accessed by key using the same syntax. The key can be any `Object`. For a `Region`, the map operator performs a non-distributed `get` in the local cache only - with no use of `netSearch`. So `myRegion[keyExpression]` is the equivalent of `myRegion.getEntry(keyExpression).getValue`.
diff --git a/geode-docs/developing/query_additional/supported_keywords.html.md.erb b/geode-docs/developing/query_additional/supported_keywords.html.md.erb
index bbc3204..314785e 100644
--- a/geode-docs/developing/query_additional/supported_keywords.html.md.erb
+++ b/geode-docs/developing/query_additional/supported_keywords.html.md.erb
@@ -19,8 +19,8 @@ See the License for the specific language governing permissions and
limitations under the License.
-->
-| Query Language Keyword | Description | Example [...]
-|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------- [...]
+| Query Language Keyword | Description | Example |
+|------------------------|-------------|---------|
| AND | Logical operator used to create complex expressions by combining two or more expressions to produce a Boolean result. When you combine two conditional expressions using the AND operator, both conditions must evaluate to true for the entire expression to be true. | See [Operators](operators.html#operators) [...]
| AS | Used to provide a label for a path expression so you can refer to the path by the label later. | See [Aliases and Synonyms](../query_select/the_from_clause.html#the_from_clause__section_AB1734C16DC348479C00FD6829B933AA) [...]
| COUNT | Returns the number of results that match the provided criteria. | See [COUNT](../query_select/the_select_statement.html#concept_85AE7D6B1E2941ED8BD2A8310A81753E__section_B2CBA00EB83F463DAF4 [...]
@@ -30,8 +30,8 @@ limitations under the License.
| <HINT> | Keyword that instructs the query engine to prefer certain indexes. | See [Using Query Index Hints](../query_index/query_index_hints.html) |
| IMPORT | Used to establish the namescope for objects. | See [IMPORT Statement](../query_select/the_import_statement.html#concept_2E9F15B2FE9041238B54736103396BF7) [...]
| IN | The IN expression is a Boolean indicating whether one expression is present inside a collection of expressions of a compatible type. | See [IN and SET](../query_select/the_where_clause.html#the_where_clause__section_AC12146509F141378E493078540950C7) [...]
-| IS\_DEFINED | Query function. Returns TRUE if the expression does not evaluate to UNDEFINED. | See [Preset Query Functions](../query_select/the_select_statement.html#concept_85AE7D6B1E2941ED8BD2A8310A81753E__section_69 [...]
-| IS\_UNDEFINED | Query function. Returns TRUE if the expression evaluates to UNDEFINED. In most queries, undefined values are not included in the query results. The IS\_UNDEFINED function allows undefined values to be included, so you can identify element with undefined values. | See [Preset Query Functions](../query_select/the_select_statement.html#concept_85AE7D6B1E2941ED8BD2A8310A81753E__section_69 [...]
+| IS\_DEFINED | Query function. Returns TRUE if the expression does not evaluate to [UNDEFINED](literals.html#literals__section_undefined). Inequality queries include undefined values in their query results. With the IS\_DEFINED function, you can limit results to only those elements with defined values. | See [Preset Query Functions](../query_select/the_select_statement.html#concept_85AE7D6B1E2941ED8BD2A8310A81753E__section_69DCAD624E9640028BC86FD67649DEB2) [...]
+| IS\_UNDEFINED | Query function. Returns TRUE if the expression evaluates to [UNDEFINED](literals.html#literals__section_undefined). With the exception of inequality queries, most queries do not include undefined values in their query results. The IS\_UNDEFINED function allows undefined values to be included, so you can identify elements with undefined values. | See [Preset Query Functions](../query_s [...]
| LIMIT | Limits the number of returned results. If you use the limit keyword, you cannot also run operations on the query result set that perform any kind of summary activities. For example trying to run add or addAll or a SelectResult from a query with a LIMIT clause throws an exception. | See [LIMIT](../query_select/the_select_statement.html#concept_85AE7D6B1E2941ED8BD2A8310A81753E__section_25D7055B33EC47B19B1 [...]
| LIKE | LIKE can be used to mean 'equals to', or if you terminate the string with a wildcard character (`%`), it behaves like 'starts with'. Note that the wildcard can only be used at the end of the comparison string. You can escape the wildcard character to represent the `%` character. You can also use the LIKE predicate if an index is present. | See [LIKE](../query_select/the_where_clause.html#the_where_clause__section_D91E0B06FFF6431490CC0BFA369425AD) [...]
| NOT | The example returns the set of portfolios that have positions. Note that NOT cannot use an index. | See [Operators](operators.html#operators) [...]
diff --git a/geode-docs/developing/query_select/the_select_statement.html.md.erb b/geode-docs/developing/query_select/the_select_statement.html.md.erb
index d472889..4d6a82e 100644
--- a/geode-docs/developing/query_select/the_select_statement.html.md.erb
+++ b/geode-docs/developing/query_select/the_select_statement.html.md.erb
@@ -149,14 +149,14 @@ If you are using ORDER BY queries, you must implement the equals and hashCode me
</tr>
<tr class="even">
<td>IS_DEFINED(expr)</td>
-<td>Returns TRUE if the expression does not evaluate to UNDEFINED.</td>
+<td>Returns TRUE if the expression does not evaluate to <a href="../query_additional/literals.html#literals__section_undefined">UNDEFINED</a>. Inequality queries include undefined values in their query results. With the IS_DEFINED function, you can limit results to only those elements with defined values.</td>
<td><pre class="pre codeblock"><code>IS_DEFINED(SELECT DISTINCT *
FROM /exampleRegion p
WHERE p.status = 'active')</code></pre></td>
</tr>
<tr class="odd">
<td>IS_UNDEFINED (expr)</td>
-<td>Returns TRUE if the expression evaluates to UNDEFINED. In most queries, undefined values are not included in the query results. The IS_UNDEFINED function allows undefined values to be included, so you can identify element with undefined values.</td>
+<td>Returns TRUE if the expression evaluates to <a href="../query_additional/literals.html#literals__section_undefined">UNDEFINED</a>. With the exception of inequality queries, most queries do not include undefined values in their query results. The IS_UNDEFINED function allows undefined values to be included, so you can identify elements with undefined values.</td>
<td><pre class="pre codeblock"><code>SELECT DISTINCT *
FROM /exampleRegion p
WHERE IS_UNDEFINED(p.status)</code></pre></td>
--
To stop receiving notification emails like this one, please contact
dbarnes@apache.org.