geode-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dbar...@apache.org
Subject [geode] branch develop updated: GEODE-4795: User Guide: Inequality queries return UNDEFINED entries
Date Thu, 08 Mar 2018 23:38:37 GMT
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 <dbarnes@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                 |
-| &lt;&gt; | not equal to             |
-| !=       | not equal to             |
 | &lt;     | less than                |
 | &lt;=    | less than or equal to    |
 | &gt;     | greater than             |
 | &gt;=    | greater than or equal to |
+|          |                          |
+| =        | equal to                 |
+| !=       | not equal to             |
+| &lt;&gt; | 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.
 | &lt;HINT&gt;           | 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 = &#39;active&#39;)</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.

Mime
View raw message