Package com.orchestranetworks.query

# Interface QueryBuilder

public interface QueryBuilder
A builder for query objects, capable of creating queries which reference tables from multiple datasets.

The same builder can be used to create multiple queries.

### Examples

The following query involves a single dataset:

            Query<Tuple> query = dataset.createQuery("SELECT * FROM customer");

The following query involves a join between two datasets, where `dataset0` is the default dataset and `dataset1` is named `s1`:

            QueryBuilder builder = dataset0.createQueryBuilder().addDataset("s1", dataset1);
            Query<Tuple> query = builder
                    .build("SELECT t1.c_custkey, t2.o_orderkey " +
                            "FROM customer t1 " +
                            "INNER JOIN s1.orders t2 " +
                            "  ON t1.c_custkey=t2.o_custkey.c_custkey ");

The default dataset `dataset0` will have the default name `_public`.

Since:
  6.0.0
See Also:
  - `Adaptation.createQueryBuilder()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `QueryBuilder`
  `addDataset(String aName, Adaptation aDataset)`
  Adds the specified dataset using the provided name.
  `Query<Tuple>`
  `build(String aSql)`
  Creates a query from the specified SQL string, whose result will return `Tuple` objects.
  `<T> Query<T>`
  `build(String aSql, Class<T> aClass)`
  Creates a query from the specified SQL string, whose result will return objects of the specified type.

- ## Method Details

  - ### addDataset

    QueryBuilder addDataset(String aName, Adaptation aDataset)
    Adds the specified dataset using the provided name. If this builder previously contained a dataset with the same name, the old value is replaced.
    Parameters:
      `aName` - the name under which the dataset is registered.
      `aDataset` - the dataset to be registered.
    Returns:
      the same builder object, with the result of this method applied. to it.
    Throws:
      `IllegalArgumentException` - if there are problems with the dataset, and it cannot be used.

  - ### build

    Query<Tuple> build(String aSql)
    Creates a query from the specified SQL string, whose result will return `Tuple` objects.

    Here is an example of a query returning `Tuple`s with several elements:

         Query<Tuple> query = queryBuilder.build("SELECT id, name, dob FROM customer");
         try (QueryResult<Tuple> result = query.getResult())
         {
                for (Tuple t : result)
                {
                        Integer id = t.get(0, Integer.class);
                        String name = t.get(1, String.class);
                        Date dob = t.get(2, Date.class);
                        ...
                }
         }

    Here is an example of a query returning `Tuple`s with one element (see `build(String, Class)` for an alternative without `Tuple`):

         Query<Tuple> query = queryBuilder.build("SELECT name FROM customer");
         try (QueryResult<Tuple> result = query.getResult())
         {
                for (Tuple t : result)
                {
                        String name = t.get(0, String.class);
                        ...
                }
         }

    Parameters:
      `aSql` - the SQL string that will be used to create the query object.
    Returns:
      a structurally valid query object which can be executed.
    Throws:
      `QueryParseException` - if the query string is not valid; for example, it contains syntax errors, it references missing tables, missing columns, etc.

  - ### build

    <T> Query<T> build(String aSql, Class<T> aClass)
    Creates a query from the specified SQL string, whose result will return objects of the specified type. See SQL documentation to have more information about the mapping between SQL and Java types.

    Here is an example of a query returning `String`s (see `build(String)` for an alternative with `Tuple`):

         Query<String> query = queryBuilder.build("SELECT name FROM customer", String.class);
         try (QueryResult<String> result = query.getResult())
         {
                for (String name : result)
                {
                        ...
                }
         }

    A typical example of the usage of this method is a COUNT query, which returns one (and only one) `Long` result:

         Query<Long> query = queryBuilder.build("SELECT COUNT(*) FROM customer", Long.class);
         try (QueryResult<Long> result = query.getResult())
         {
                Long count = result.iterator().next();
                ...
         }

    Parameters:
      `aSql` - the SQL string that will be used to create the query object.
      `aClass` - the class representing the row type of the query result; either `Tuple`, or in the case of a 1-element row, the mapped Java type of this element.
    Returns:
      a structurally valid query object which can be executed.
    Throws:
      `QueryParseException` - if the SQL query is not valid; for example, it contains syntax errors, it references missing tables, missing columns, etc.