# Package org.apache.sis.storage.sql

package org.apache.sis.storage.sql
Data store capable to read and write features using a JDBC connection to a database. `SimpleFeatureStore` takes one or more tables at construction time. Each enumerated table is represented by a `FeatureType`. Each row in those table represents a `Feature` instance. Each relation defined by a foreigner key is represented by an `FeatureAssociationRole` to another feature (with transitive dependencies automatically resolved), and the other columns are represented by `AttributeType`.

The storage of spatial features in SQL databases is described by the OGC Simple feature access - Part 2: SQL option international standard, also known as ISO 19125-2. The implementation of geometric objects and their operations must be provided by the database. This is sometimes provided by an extension that needs to be installed explicitly. For example, when using PostgreSQL, the PostGIS extension is recommended.

The tables to use as resource definitions must be specified at construction time. There is no automatic discovery mechanism. Note that discovery may be done by other modules. For example, Geopackage module uses the `"gpkg_contents"` table.

## Performance tips

A subset of features can be obtained by applying filters on the stream returned by `FeatureSet​.features(boolean)`. While the filter can be any `Predicate`, performances will be much better if they are instances of `Filter` because Apache SIS will know how to translate some of them to SQL statements.

In filter expressions like `ST_Intersects(A,B)` where the A and B parameters are two sub-expressions evaluating to geometry values, if one of those expressions is a literal, then that literal should be B. The reason is because the SQLMM standard requires us to project B in the Coordinate Reference System of A. If B 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.

Limitation: if a parent feature contains association to other features (defined by foreigner keys), those other features are created at the same time as the parent feature. There is no lazy instantiation yet. Performances should be okay if each parent feature references only a small amount of children.

Since:
  1.0

- Related Packages
  Module
  Package
  Description
  org.apache.sis.storage
  org.apache.sis.storage
  Data store base types for retrieving and saving geospatial data in various storage formats.
- Classes
  Class
  Description
  DataAccess
  Low-level accesses to the database content.
  ResourceDefinition
  Definition of a resource (table, view or query) to include in a `SQLStore`.
  SimpleFeatureStore
  A concrete data store capable to read and write features from/to a spatial SQL database.
  SQLStore
  An abstract data store for reading or writing resources from/to a spatial database.
  SQLStoreProvider
  Provider of `SQLStore` instances.