feat: add sample code for multiple inequalities indexing consideratio…

…n query (#1579)

* feat: add sample code for multiple inequalities indexing consideration query

* fix formatting

* fix formatting

* fix formatting

* fix formatting

* Add index

* Correct indexes

* Add orderfileds query

* fix orderby asc

* Move region tag to include import statements

samples/snippets/src/main/java/com/example/datastore/filters/IndexingConsiderationQuery.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.datastore.filters;
+
+// sample-metadata:
+//   title: Queries with indexing considerations
+//   description: The following query produces a result set
+//   that is ordered according to the index definition.
+
+// [START datastore_query_indexing_considerations]
+
+import com.google.cloud.datastore.Datastore;
+import com.google.cloud.datastore.DatastoreOptions;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.Query;
+import com.google.cloud.datastore.QueryResults;
+import com.google.cloud.datastore.StructuredQuery.CompositeFilter;
+import com.google.cloud.datastore.StructuredQuery.Filter;
+import com.google.cloud.datastore.StructuredQuery.OrderBy;
+import com.google.cloud.datastore.StructuredQuery.PropertyFilter;
+
+public class IndexingConsiderationQuery {
+  public static void invoke() throws Exception {
+
+    // Instantiates a client
+    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
+
+    // Build a query with multi inequal filters and optimized index order of index properties.
+    Query<Entity> query = Query.newEntityQueryBuilder()
+            .setKind("employees")
+            .setFilter(CompositeFilter.and(
+                    PropertyFilter.gt("salary", 100000),
+                    PropertyFilter.gt("experience", 0)))
+            .setOrderBy(OrderBy.asc("salary"), OrderBy.asc("experience"))
+            .build();
+
+    // Get the results back from Datastore
+    QueryResults<Entity> results = datastore.run(query);
+
+    if (!results.hasNext()) {
+      throw new Exception("query yielded no results");
+    }
+
+    while (results.hasNext()) {
+      Entity entity = results.next();
+      System.out.printf("Entity: %s%n", entity);
+    }
+  }
+}
+// [END datastore_query_indexing_considerations]

samples/snippets/src/main/java/com/example/datastore/filters/OrderFieldsQuery.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.datastore.filters;
+
+// sample-metadata:
+//   title: Queries with order fileds
+//   description: The following query order properties
+//   in the decreasing order of query constraint selectivity.
+
+// [START datastore_query_order_fields]
+
+import com.google.cloud.datastore.Datastore;
+import com.google.cloud.datastore.DatastoreOptions;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.Query;
+import com.google.cloud.datastore.QueryResults;
+import com.google.cloud.datastore.StructuredQuery.Filter;
+import com.google.cloud.datastore.StructuredQuery.OrderBy;
+import com.google.cloud.datastore.StructuredQuery.PropertyFilter;
+
+public class OrderFieldsQuery {
+  public static void invoke() throws Exception {
+
+    // Instantiates a client
+    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
+
+    // Build a query with order properties in the decreasing order of query constraint selectivity.
+    Query<Entity> query =
+            Query.newEntityQueryBuilder()
+                    .setKind("employees")
+                    .setFilter(PropertyFilter.gt("salary", 100000))
+                    .setOrderBy(OrderBy.asc("salary"))
+                    .build();
+
+    // Get the results back from Datastore
+    QueryResults<Entity> results = datastore.run(query);
+    // Order results by `experience`
+
+    if (!results.hasNext()) {
+      throw new Exception("query yielded no results");
+    }
+
+    while (results.hasNext()) {
+      Entity entity = results.next();
+      System.out.printf("Entity: %s%n", entity);
+    }
+  }
+}
+// [END datastore_query_order_fields]

samples/snippets/src/test/java/com/example/datastore/filters/MultiIneqQuerySampleIT.java

@@ -0,0 +1,96 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.datastore.filters;
+
+import com.google.cloud.datastore.Datastore;
+import com.google.cloud.datastore.DatastoreOptions;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.Key;
+import com.rule.SystemsOutRule;
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+@RunWith(JUnit4.class)
+@SuppressWarnings("checkstyle:abbreviationaswordinname")
+public class MultiIneqQuerySampleIT {
+
+  private final Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
+
+  private Key employeeKey1;
+  private Key employeeKey2;
+  private Key employeeKey3;
+
+  @Rule
+  public final SystemsOutRule systemsOutRule = new SystemsOutRule();
+
+  @Before
+  public void setUp() {
+    employeeKey1 = datastore.newKeyFactory().setKind("employees").newKey("employee1");
+    Entity employee1 = Entity.newBuilder(employeeKey1)
+            .set("name", "Alice")
+            .set("salary", 100001)
+            .set("experience", 10)
+            .build();
+
+    employeeKey2 = datastore.newKeyFactory().setKind("employees").newKey("employee2");
+    Entity employee2 = Entity.newBuilder(employeeKey2)
+            .set("name", "Bob")
+            .set("salary", 90000)
+            .set("experience", 5)
+            .build();
+
+    employeeKey3 = datastore.newKeyFactory().setKind("employees").newKey("employee3");
+    Entity employee3 = Entity.newBuilder(employeeKey3)
+            .set("name", "Jay")
+            .set("salary", 120000)
+            .set("experience", 15)
+            .build();
+
+    datastore.put(employee1);
+    datastore.put(employee2);
+    datastore.put(employee3);
+  }
+
+  @After
+  public void tearDown() {
+    datastore.delete(employeeKey1);
+    datastore.delete(employeeKey2);
+    datastore.delete(employeeKey3);
+  }
+
+  @Test
+  public void testIndexingConsiderationQuery() throws Exception {
+    // Act
+    IndexingConsiderationQuery.invoke();
+
+    // Assert
+    systemsOutRule.assertContains("Entity");
+  }
+
+  @Test
+  public void testOrderFieldsQuery() throws Exception {
+    // Act
+    OrderFieldsQuery.invoke();
+
+    // Assert
+    systemsOutRule.assertContains("Entity");
+  }
+}

samples/snippets/src/test/resources/index.yaml

@@ -23,3 +23,7 @@ indexes:
   properties:
   - name: tag
   - name: tag
+- kind: employees
+  properties:
+    - name: salary
+    - name: experience