Package org.apache.ignite

Class IgniteJdbcDriver

  • All Implemented Interfaces:
    Driver
    public class IgniteJdbcDriver
extends Object
implements Driver
    JDBC driver implementation for In-Memory Data Grid.

    Driver allows to get distributed data from Ignite cache using standard SQL queries and standard JDBC API. It will automatically get only fields that you actually need from objects stored in cache.

    Limitations

    Data in Ignite cache is usually distributed across several nodes, so some queries may not work as expected since the query will be sent to each individual node and results will then be collected and returned as JDBC result set. Keep in mind following limitations (not applied if data is queried from one node only, or data is fully co-located or fully replicated on multiple nodes):
    • Joins will work correctly only if joined objects are stored in collocated mode. Refer to AffinityKey javadoc for more details.
    • Note that if you are connected to local or replicated cache, all data will be queried only on one node, not depending on what caches participate in the query (some data from partitioned cache can be lost). And visa versa, if you are connected to partitioned cache, data from replicated caches will be duplicated.

    SQL Notice

    Driver allows to query data from several caches. Cache that driver is connected to is treated as default schema in this case. Other caches can be referenced by their names.

    Note that cache name is case sensitive and you have to always specify it in quotes.

    Dependencies

    JDBC driver is located in main Ignite JAR and depends on all libraries located in IGNITE_HOME/libs folder. So if you are using JDBC driver in any external tool, you have to add main Ignite JAR will all dependencies to its classpath.

    Configuration

    JDBC driver return Ignite client node based connection.

    Configuration of Ignite client node based connection

    JDBC connection URL has the following pattern: jdbc:ignite:cfg://[<params>@]<config_url>.
    <config_url> represents any valid URL which points to Ignite configuration file. It is required.
    <params> are optional and have the following format: param1=value1:param2=value2:...:paramN=valueN.
    The following parameters are supported:
    • cache - cache name. If it is not defined than default cache will be used.
    • nodeId - ID of node where query will be executed. It can be useful for querying through local caches. If node with provided ID doesn't exist, exception is thrown.
    • local - query will be executed only on local node. Use this parameter with nodeId parameter. Default value is false.
    • collocated - flag that used for optimization purposes. Whenever Ignite executes a distributed query, it sends sub-queries to individual cluster members. If you know in advance that the elements of your query selection are collocated together on the same node, usually based on some affinity-key, Ignite can make significant performance and network optimizations. Default value is false.
    • distributedJoins - enables support of distributed joins feature. This flag does not make sense in combination with local and/or collocated flags with true value or in case of querying of local cache. Default value is false.
    • enforceJoinOrder - Sets flag to enforce join order of tables in the query. If set to true query optimizer will not reorder tables in join. By default is false.
    • lazy - Sets flag to enable lazy query execution. By default Ignite attempts to fetch the whole query result set to memory and send it to the client. For small and medium result sets this provides optimal performance and minimize duration of internal database locks, thus increasing concurrency.

      If result set is too big to fit in available memory this could lead to excessive GC pauses and even OutOfMemoryError. Use this flag as a hint for Ignite to fetch result set lazily, thus minimizing memory consumption at the cost of moderate performance hit.

      Defaults to false, meaning that the whole result set is fetched to memory eagerly.

    Example

      // Open JDBC connection.
 Connection conn = DriverManager.getConnection("jdbc:ignite:cfg//cache=persons@file:///etc/configs/ignite-jdbc.xml");

 // Query persons' names
 ResultSet rs = conn.createStatement().executeQuery("select name from Person");

 while (rs.next()) {
     String name = rs.getString(1);

     ...
 }

 // Query persons with specific age
 PreparedStatement stmt = conn.prepareStatement("select name, age from Person where age = ?");

 stmt.setInt(1, 30);

 ResultSet rs = stmt.executeQuery();

 while (rs.next()) {
     String name = rs.getString("name");
     int age = rs.getInt("age");

     ...
 }