Package com.apple.foundationdb.relational.api

Interface RelationalDirectAccessStatement

  • All Superinterfaces:
    java.lang.AutoCloseable
    All Known Subinterfaces:
    RelationalStatement
    public interface RelationalDirectAccessStatement
extends java.lang.AutoCloseable

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      void close()
      Close method to free up resources managed by this statement.
      default int executeDelete​(java.lang.String tableName, java.lang.Iterable<KeySet> keys)
      Delete one or more records from the specified table, specified by key, if such records exist.
      default int executeDelete​(java.lang.String tableName, java.lang.Iterable<KeySet> keys, Options options)  
      default int executeDelete​(java.lang.String tableName, java.util.Iterator<KeySet> keys)
      Delete one or more records from the specified table, specified by key, if such records exist.
      int executeDelete​(java.lang.String tableName, java.util.Iterator<KeySet> keys, Options options)  
      void executeDeleteRange​(java.lang.String tableName, KeySet keyPrefix, Options options)
      This can be used to delete contiguous rows on a table based on a certain PK range.
      RelationalResultSet executeGet​(java.lang.String tableName, KeySet key, Options options)
      Get a single record from the system by key.
      default int executeInsert​(java.lang.String tableName, RelationalStruct data)
      Insert a record into the specified table, updating any indexes as necessary to maintain consistency.
      default int executeInsert​(java.lang.String tableName, RelationalStruct data, Options options)
      Insert one or more records into the specified table, updating any indexes as necessary to maintain consistency.
      default int executeInsert​(java.lang.String tableName, java.util.List<RelationalStruct> data)
      Insert one or more records into the specified table, updating any indexes as necessary to maintain consistency.
      int executeInsert​(java.lang.String tableName, java.util.List<RelationalStruct> data, Options options)
      Insert one or more records into the specified table, updating any indexes as necessary to maintain consistency.
      RelationalResultSet executeScan​(java.lang.String tableName, KeySet keyPrefix, Options options)
      Execute a multi-row scan against the database, returning a RelationalResultSet containing the results of the scan.

    • Method Detail

      • executeScan

        @Nonnull
RelationalResultSet executeScan​(@Nonnull
                                java.lang.String tableName,
                                @Nonnull
                                KeySet keyPrefix,
                                @Nonnull
                                Options options)
                         throws java.sql.SQLException
        Execute a multi-row scan against the database, returning a RelationalResultSet containing the results of the scan. This can be used to scan contiguous rows on a table based on a certain PK range. The range should be provided via a key prefix. 
         Examples:

 CREATE TABLE FOO(a bigint, b bigint, c bigint, primary key(a, b))
 INSERT INTO FOO VALUES [
     {"A": 1, "B": 1, "C": 2},
     {"A": 1, "B": 2, "C": 3},
     {"A": 2, "B": 3, "C": 4}
 ]

 // Scans every row
 executeScan("FOO", new KeySet(), Options.NONE)

 // Scans the first two rows
 executeScan("FOO", new KeySet().setKeyColumn("A", 1), Options.NONE)

 // Scans only the first row
 executeScan("FOO", new KeySet().setKeyColumn("A", 1).setKeyColumn("B", 1), Options.NONE)

 // Fails because C is not part of the Primary Key
 executeScan("FOO", new KeySet().setKeyColumn("C", 2), Options.NONE)

 // Fails because B is not a prefix of the Primary Key
 executeScan("FOO", new KeySet().setKeyColumn("B", 1), Options.NONE)

        The caller can specify some execution-level options, which can be used to control the execution path that the execution. Specifically, the following options are honored:

        • use.index: the name of a specific index to use during scan
        • continuation: The value of the continuation to use for the scan
        Parameters:
        tableName - the name of the table.
        keyPrefix - the key prefix to use when scanning entries.
        options - options that can be used to configure the scan.
        Returns:
        a ResultSet containing the entire record in the underlying scan.
        Throws:
        java.sql.SQLException - if something goes wrong. Use the Error code to determine exactly what.

      • executeGet

        @Nonnull
RelationalResultSet executeGet​(@Nonnull
                               java.lang.String tableName,
                               @Nonnull
                               KeySet key,
                               @Nonnull
                               Options options)
                        throws java.sql.SQLException
        Get a single record from the system by key.

        This constructs a primary key from the specified KeySet according to the table definition, and then performs a single-row lookup. This is equivalent to executing a scan on the range bounds, but can potentially be more efficiently executed.

        Parameters:
        tableName - the name of the table to get data from
        key - The constructor for the key to fetch by
        options - the options for the GET operation.
        Returns:
        a ResultSet containing the entire record from the resulting GET, either 1 row or 0. If the row does not exist the ResultSet will be empty
        Throws:
        java.sql.SQLException - If something geos wrong. Use the error code to determine exactly what.

      • executeInsert

        default int executeInsert​(@Nonnull
                          java.lang.String tableName,
                          @Nonnull
                          RelationalStruct data)
                   throws java.sql.SQLException
        Insert a record into the specified table, updating any indexes as necessary to maintain consistency.
        Parameters:
        tableName - the name of the table to insert into.
        data - the data to insert.
        Returns:
        the number of records inserted.
        Throws:
        java.sql.SQLException - If something goes wrong. Use the error code to determine exactly what.

      • executeInsert

        default int executeInsert​(@Nonnull
                          java.lang.String tableName,
                          @Nonnull
                          RelationalStruct data,
                          @Nonnull
                          Options options)
                   throws java.sql.SQLException
        Insert one or more records into the specified table, updating any indexes as necessary to maintain consistency.
        Parameters:
        tableName - the name of the table to insert into.
        data - the data to insert.
        Returns:
        the number of records inserted.
        Throws:
        java.sql.SQLException - If something goes wrong. Use the error code to determine exactly what.

      • executeInsert

        default int executeInsert​(@Nonnull
                          java.lang.String tableName,
                          @Nonnull
                          java.util.List<RelationalStruct> data)
                   throws java.sql.SQLException
        Insert one or more records into the specified table, updating any indexes as necessary to maintain consistency.
        Parameters:
        tableName - the name of the table to insert into.
        data - the data to insert.
        Returns:
        the number of records inserted.
        Throws:
        java.sql.SQLException - If something goes wrong. Use the error code to determine exactly what.

      • executeInsert

        int executeInsert​(@Nonnull
                  java.lang.String tableName,
                  @Nonnull
                  java.util.List<RelationalStruct> data,
                  @Nonnull
                  Options options)
           throws java.sql.SQLException
        Insert one or more records into the specified table, updating any indexes as necessary to maintain consistency.
        Parameters:
        tableName - the name of the table to insert into.
        data - the data to insert.
        options - options to apply to the insert.
        Returns:
        the number of records inserted.
        Throws:
        java.sql.SQLException - If something goes wrong. Use the error code to determine exactly what.

      • executeDelete

        default int executeDelete​(@Nonnull
                          java.lang.String tableName,
                          @Nonnull
                          java.lang.Iterable<KeySet> keys)
                   throws java.sql.SQLException
        Delete one or more records from the specified table, specified by key, if such records exist.

        equivalent to executeDelete(String, Iterator), but with a marginally nicer user experience of not needing to call .iterator()

        Parameters:
        tableName - the name of the table to delete from
        keys - the keys to delete
        Returns:
        the number of records deleted
        Throws:
        java.sql.SQLException - if something goes wrong. Use the error code to determine exactly what.

      • executeDelete

        default int executeDelete​(@Nonnull
                          java.lang.String tableName,
                          @Nonnull
                          java.lang.Iterable<KeySet> keys,
                          @Nonnull
                          Options options)
                   throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • executeDelete

        default int executeDelete​(@Nonnull
                          java.lang.String tableName,
                          @Nonnull
                          java.util.Iterator<KeySet> keys)
                   throws java.sql.SQLException
        Delete one or more records from the specified table, specified by key, if such records exist.
        Parameters:
        tableName - the name of the table to delete from
        keys - the keys to delete
        Returns:
        the number of records deleted
        Throws:
        java.sql.SQLException - if something goes wrong. Use the error code to determine exactly what.

      • executeDelete

        int executeDelete​(@Nonnull
                  java.lang.String tableName,
                  @Nonnull
                  java.util.Iterator<KeySet> keys,
                  @Nonnull
                  Options options)
           throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • executeDeleteRange

        void executeDeleteRange​(@Nonnull
                        java.lang.String tableName,
                        @Nonnull
                        KeySet keyPrefix,
                        @Nonnull
                        Options options)
                 throws java.sql.SQLException
        This can be used to delete contiguous rows on a table based on a certain PK range. The range should be provided via a key prefix. 
         Examples:

 CREATE TABLE FOO(a bigint, b bigint, c bigint, primary key(a, b))
 INSERT INTO FOO VALUES [
     {"A": 1, "B": 1, "C": 2},
     {"A": 1, "B": 2, "C": 3},
     {"A": 2, "B": 3, "C": 4}
 ]

 // deletes every row
 executeDeleteRange("FOO", new KeySet(), Options.NONE)

 // deletes the first two rows
 executeDeleteRange("FOO", new KeySet().setKeyColumn("A", 1), Options.NONE)

 // deletes only the first row
 executeDeleteRange("FOO", new KeySet().setKeyColumn("A", 1).setKeyColumn("B", 1), Options.NONE)

 // Fails because C is not part of the Primary Key
 executeDeleteRange("FOO", new KeySet().setKeyColumn("C", 2), Options.NONE)

 // Fails because B is not a prefix of the Primary Key
 executeDeleteRange("FOO", new KeySet().setKeyColumn("B", 1), Options.NONE)
        Parameters:
        tableName - the name of the table to delete from
        keyPrefix - the key prefix to use when deleting entries
        options - options that can be used to configure the delete
        Throws:
        java.sql.SQLException - if something goes wrong. Use the error code to determine exactly what.

      • close

        void close()
    throws java.sql.SQLException
        Close method to free up resources managed by this statement.
        Specified by:
        close in interface java.lang.AutoCloseable
        Throws:
        java.sql.SQLException - for errors encountered while closing