You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2021/08/31 17:25:16 UTC
[sis] 01/07: Add performance tips about the use of filters.
This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git
commit 943f91bccec59cf1a7811d33f7990b1c51cea433
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Mon Aug 30 10:43:25 2021 +0200
Add performance tips about the use of filters.
---
.../java/org/apache/sis/filter/package-info.java | 27 ++++++++++++++++++----
.../org/apache/sis/storage/sql/package-info.java | 13 +++++++++++
2 files changed, 35 insertions(+), 5 deletions(-)
diff --git a/core/sis-feature/src/main/java/org/apache/sis/filter/package-info.java b/core/sis-feature/src/main/java/org/apache/sis/filter/package-info.java
index 84147a9..9004cfa 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/filter/package-info.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/filter/package-info.java
@@ -26,13 +26,30 @@
* Filters and expressions may contain heterogeneous coordinate reference systems.
* Apache SIS tries to handle differences in the following way:
* <ul>
- * <li>If all evaluated geometries define a {@code srid}, but they are not the same, try to project them in a common space.
- * The strategy is guided by {@linkplain org.apache.sis.referencing.CRS#suggestCommonTarget Referencing utility method}.
- * If it cannot provide a common space, fail any ongoing operation.</li>
- * <li>If no geometry contains any {@code srid}, consider they are defined in the same space, and proceed.</li>
- * <li>If one geometry define a CRS but the other do not, consider that an ambiguity resides: fail.</li>
+ * <li>If at least one geometry does not has a CRS, then SIS assumes that the geometries are in the same space.</li>
+ * <li>If all geometries are in the same CRS, no coordinate operation is applied.</li>
+ * <li>If geometries have non-null but different CRS, then SIS tries to project the geometries in a common space:
+ * <ul>
+ * <li>For SQLMM operations, the CRS of the first operand is used (as required by the specification).</li>
+ * <li>For other operations, the common CRS is chosen by
+ * {@linkplain org.apache.sis.referencing.CRS#suggestCommonTarget referencing utility method}.
+ * If that method cannot provide a common space,
+ * then an {@link org.opengis.filter.InvalidFilterValueException} is thrown.</li>
+ * </ul>
+ * </li>
* </ul>
*
+ * <h2>Performance tips</h2>
+ * <p>In expressions like {@code ST_Intersects(A,B)} where the <var>A</var> and <var>B</var> parameters are two
+ * sub-expressions evaluating to geometry values, if one of those expressions is a literal, then that literal
+ * should be <var>B</var>. The reason is because SQLMM specification requires us to project <var>B</var>
+ * in the Coordinate Reference System of <var>A</var>. If <var>B</var> is a literal, Apache SIS can do
+ * this transformation only once before to start any evaluation instead of every time that the expression
+ * needs to be evaluated.</p>
+ *
+ * <p>Data store implementations should apply {@link org.apache.sis.filter.Optimization} on the filters
+ * before to evaluate them.</p>
+ *
* <h2>Thread-safety</h2>
* All filter and expression implementations provided by Apache SIS are thread-safe.
* They are not necessarily stateless however; for example a filter may remember which
diff --git a/storage/sis-sqlstore/src/main/java/org/apache/sis/storage/sql/package-info.java b/storage/sis-sqlstore/src/main/java/org/apache/sis/storage/sql/package-info.java
index 50f6476..85e98ec 100644
--- a/storage/sis-sqlstore/src/main/java/org/apache/sis/storage/sql/package-info.java
+++ b/storage/sis-sqlstore/src/main/java/org/apache/sis/storage/sql/package-info.java
@@ -31,6 +31,19 @@
* be provided by the database (sometime through an extension, for example PostGIS on PostgreSQL databases).
* This Java package uses those provided types and operations.</p>
*
+ * <h2>Performance tips</h2>
+ * <p>A subset of features can be obtained by applying filters on the stream returned by
+ * {@link org.apache.sis.storage.FeatureSet#features(boolean)}.
+ * While the filter can be any {@link java.util.function.Predicate},
+ * performances will be much better if they are instances of {@link org.opengis.filter.Filter}
+ * because Apache SIS will know how to translate some of them to SQL statements.</p>
+ *
+ * <p>In filter expressions like {@code ST_Intersects(A,B)} where the <var>A</var> and <var>B</var> parameters are
+ * two sub-expressions evaluating to geometry values, if one of those expressions is a literal, then that literal
+ * should be <var>B</var>. The reason is because the SQLMM standard requires us to project <var>B</var> in the
+ * Coordinate Reference System of <var>A</var>. If <var>B</var> is a literal, Apache SIS can do this transformation
+ * only once before to start the filtering process instead of every time that the filter needs to be evaluated.</p>
+ *
* <h2>Limitations</h2>
* <ul>
* <li>Current implementation does not scan the {@code "GEOMETRY_COLUMNS"} (from Simple Feature Access)