TaQLJoin.h

Go to the documentation of this file.

//# TaQLJoin.h: Class handling the condition of the join clause
//# Copyright (C) 2022
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//#        Internet email: casa-feedback@nrao.edu.
//#        Postal address: AIPS++ Project Office
//#                        National Radio Astronomy Observatory
//#                        520 Edgemont Road
//#                        Charlottesville, VA 22903-2475 USA
 
#ifndef TABLES_TAQLJOIN_H
#define TABLES_TAQLJOIN_H
 
#include <casacore/casa/aips.h>
#include <casacore/tables/TaQL/ExprDerNode.h>
#include <casacore/tables/TaQL/ExprNodeSetOpt.h>
#include <vector>
 
namespace casacore { //# NAMESPACE CASACORE - BEGIN
 
  //# Forward declarations.
  class TableExprNode;
  class TableExprNodeSetElemCont;
  class TableParseJoin;
  
  // <summary>
  // Base class for handling a comparison in the join clause in a TaQL command
  // </summary>
  // <use visibility=local>
  // <reviewed reviewer="Tammo Jan Dijkema" date="2022/12/15" tests="tTableGramJoin">
  // </reviewed>
  // <synopsis>
  // </synopsis> 
 
  class TaQLJoinBase
  {
  public:
    virtual ~TaQLJoinBase() = default;
 
    // Find the row number. <0 means not found.
    virtual Int64 findRow (const TableExprId&) = 0;
  };
 
 
  // <summary>
  // Class holding the row number as the final level in the comparison tree
  // </summary>
  // <use visibility=local>
  // <reviewed reviewer="Tammo Jan Dijkema" date="2022/12/15" tests="tTableGramJoin">
  // </reviewed>
  // <synopsis>
  // Objects of this class form the lowest level in a TaQLJoin tree. It only
  // contains a row number telling which row in the join table contains the
  // values at the higher levels in the tree.
  // </synopsis> 
 
  class TaQLJoinRow : public TaQLJoinBase
  {
  public:
    TaQLJoinRow (Int64 row)
      : itsRow (row)
    {}
    ~TaQLJoinRow() override = default;
 
    // Return the row number.
    Int64 findRow (const TableExprId&) override;
    
  private:
    Int64 itsRow;
  };
 
 
  // <summary>
  // Class holding a comparison part of a join condition
  // </summary>
  // <use visibility=local>
  // <reviewed reviewer="Tammo Jan Dijkema" date="2022/12/15" tests="tTableGramJoin">
  // </reviewed>
  // <synopsis>
  // TaQLJoin holds a vector of nested TaQLJoinBase objects, one for each
  // unique value or interval in the join table. It uses TableExprNodeSetOptBase
  // to hold the values and the index in the vector of TaQLJoinBase objects.
  // The data types that can be used in a join condition are the same as those
  // supported by TableExprNodeSetOptBase; that is: integer and string for a
  // discrete value and int, double, datetime and string for an interval.
  // Note that in the interval case int and datetime are handled as double.
  //
  // Note that at the lowest level the vector of TaQLJoinBase objects contains
  // TaQLJoinRow objects holding the join table row number. The TaQLJoin objects
  // at the higher levels contain the index in the vector at the next level.
  //
  // The class contains static functions to build the tree given the left and
  // right part of a comparison, where left is an expression using the main table
  // and right using the join table. The right expression gives the values to
  // build the tree as sketched above.
  //
  // <example>
  // <srcblock>
  //   SELECT t1.COL1, t2.NAME FROM maintab t1 JOIN jointab t2 ON
  //                             t1.COL1 = t2.IDCOL
  //                         AND t1.TIME AROUND t2.TIME IN t2.INTERVAL
  // </srcblock>
  // In this example the main and join table are joined on 2 condition parts.
  // First the equality match of COL1 and IDCOL, second the interval match on TIME.
  // Note that the NAME column from the join table are selected, thus
  // the join is used to find the name for each row in the main table.
  // <br>The join table columns may contain something like below.
  // Thus 4 unique IDCOL values, each having 2 time intervals.
  // <srcblock>
  //   IDCOL     TIME     INTERVAL      NAME
  //     0        tm1        d1        name01
  //     1        tm1        d1        name11
  //     2        tm1        d1        name21
  //     3        tm1        d1        name31
  //     0        tm2        d2        name02
  //     1        tm2        d2        name12
  //     2        tm2        d2        name22
  //     3        tm2        d2        name32
  // </srcblock>
  // The TaQLJoin tree will consist of 3 levels. The first level handles the
  // equality match. It consists of a single TaQLJoin object containing a vector
  // of second level TaQLJoin objects, one for each unique IDCOL value. 
  // The second level handles the TIME match. The third level contains the row
  // number for each IDCOL/TIME pair. Schematically:
  // <srcblock>
  // level 1 TaQLJoin, IDCOL:    0          1          2         3
  // level 2 TaQLJoin, TIME:  tm1 tm2    tm1 tm2    tm1 tm2    tm1 tm2
  // level 3 TaQLJoinRow:      0   1      2   3      4   5      6   7
  // </srcblock>
  // To find the matching join table row means that first the matching
  // IDCOL is found at level 1, thereafter at level 2 the matching interval
  // for that IDCOL.Level 3 gives the correct row number in the join table.
  // </example>
  // </synopsis> 
 
  class TaQLJoin : public TaQLJoinBase
  {
  public:
    TaQLJoin (const TENShPtr& mainNode, const TENShPtr& joinNode,
              const std::vector<std::shared_ptr<TaQLJoinBase>>& children);
    
    ~TaQLJoin() override = default;
 
    // Find the row number in the join table for the given row in the main table.
    Int64 findRow (const TableExprId&) override;
 
    // From the given level on create nested TaQLJoin nodes.
    // It use makeOptDiscrete or makeOptInterval to create the appropriate
    // TableExprNodeSetOptBase object.
    static std::shared_ptr<TaQLJoinBase> createRecursive
    (const std::vector<TableExprNode>& mainNodes,
     const std::vector<TableExprNode>& joinNodes,
     const std::vector<rownr_t>& rows,
     size_t level);
 
    // Create nested TaQLJoin nodes for a join expression part at the given level
    // using discrete values.
    // Thereafter createRecursive is called for the next level.
    template<typename T>
    static std::shared_ptr<TaQLJoinBase> makeOptDiscrete
    (TableExprNodeRep& node,
     const std::vector<TableExprNode>& mainNodes,
     const std::vector<TableExprNode>& joinNodes,
     const std::vector<rownr_t>& rows,
     size_t level);
 
    // Create nested TaQLJoin nodes for a join expression part at the given level
    // using intervals.
    // Thereafter createRecursive is called for the next level.
    template<typename T>
    static std::shared_ptr<TaQLJoinBase> makeOptInterval
    (const TableExprNodeSet& set,
     const std::vector<TableExprNode>& mainNodes,
     const std::vector<TableExprNode>& joinNodes,
     const std::vector<rownr_t>& rows,
     size_t level);
 
  private:
    TENShPtr itsMainNode;
    TENShPtr itsJoinNode;                  // only used for automatic deletion
    TableExprNodeSetOptBase* itsOptSet;    // same ptr as itsJoinNode
    std::vector<std::shared_ptr<TaQLJoinBase>> itsChildren;
  };
 
 
  // <summary>
  // A column in a join table
  // </summary>
  // <use visibility=local>
  // <reviewed reviewer="Tammo Jan Dijkema" date="2022/12/15" tests="tTableGramJoin">
  // </reviewed>
  // <synopsis>
  // TaQLJoinColumn contains the TableExprNodeColumn object for a
  // column in a join table. It is used to find a value in the join column
  // for a row in the main table. It uses the TableParseJoin object to find
  // the row in the join table given the row in the main table.
  // </synopsis> 
 
  class TaQLJoinColumn : public TableExprNodeRep
  {
  public:
    TaQLJoinColumn (const TENShPtr& columnNode, const TableParseJoin&);
    
    ~TaQLJoinColumn() override = default;
 
    // Get the table info for this column.
    TableExprInfo getTableInfo() const override;
 
    // Get the data for the given id.
    // Using the Join object it maps the row number in the main table
    // to the row number in the join table.
    // <group>
    MArray<Bool> getArrayBool         (const TableExprId& id) override;
    MArray<Int64> getArrayInt         (const TableExprId& id) override;
    MArray<Double> getArrayDouble     (const TableExprId& id) override;
    MArray<DComplex> getArrayDComplex (const TableExprId& id) override;
    MArray<String> getArrayString     (const TableExprId& id) override;
    MArray<MVTime> getArrayDate       (const TableExprId& id) override;
    // </group>
 
    // Clear the internal data vector (in derived classes).
    virtual void clear();
 
    // Make the appropriate TaQLJoinColumn object.
    static TableExprNode makeColumnNode (const TENShPtr& columnNode,
                                         const TableParseJoin&);
    
  protected:
    TENShPtr              itsColumn;
    const TableParseJoin& itsJoin;
  };
 
 
  // <summary>
  // A scalar column of the given type in a join table
  // </summary>
  // <use visibility=local>
  // <reviewed reviewer="Tammo Jan Dijkema" date="2022/12/15" tests="tTableGramJoin">
  // </reviewed>
  // <synopsis>
  // TaQLJoinArrayColumn contains the TableExprNodeColumn object for an array
  // column in a join table. It is used to find a value in the join column
  // for a row in the main table. It uses the TableParseJoin object to find
  // the row in the join table given the row in the main table.
  // </synopsis> 
 
  class TaQLJoinColumnBool : public TaQLJoinColumn
  {
  public:
    TaQLJoinColumnBool (const TENShPtr& columnNode, const TableParseJoin&);
    ~TaQLJoinColumnBool() override = default;
    Bool getBool (const TableExprId& id) override;
    void clear() override;
  private:
    Vector<Bool> itsData;
  };
 
  class TaQLJoinColumnInt : public TaQLJoinColumn
  {
  public:
    TaQLJoinColumnInt (const TENShPtr& columnNode, const TableParseJoin&);
    ~TaQLJoinColumnInt() override = default;
    Int64 getInt (const TableExprId& id) override;
    void clear() override;
  private:
    Vector<Int64> itsData;
  };
 
  class TaQLJoinColumnDouble : public TaQLJoinColumn
  {
  public:
    TaQLJoinColumnDouble (const TENShPtr& columnNode, const TableParseJoin&);
    ~TaQLJoinColumnDouble() override = default;
    Double getDouble (const TableExprId& id) override;
    void clear() override;
  private:
    Vector<Double> itsData;
  };
 
  class TaQLJoinColumnDComplex : public TaQLJoinColumn
  {
  public:
    TaQLJoinColumnDComplex (const TENShPtr& columnNode, const TableParseJoin&);
    ~TaQLJoinColumnDComplex() override = default;
    DComplex getDComplex (const TableExprId& id) override;
    void clear() override;
  private:
    Vector<DComplex> itsData;
  };
 
  class TaQLJoinColumnString : public TaQLJoinColumn
  {
  public:
    TaQLJoinColumnString (const TENShPtr& columnNode, const TableParseJoin&);
    ~TaQLJoinColumnString() override = default;
    String getString (const TableExprId& id) override;
    void clear() override;
  private:
    Vector<String> itsData;
  };
 
  class TaQLJoinColumnDate : public TaQLJoinColumn
  {
  public:
    TaQLJoinColumnDate (const TENShPtr& columnNode, const TableParseJoin&);
    ~TaQLJoinColumnDate() override = default;
    MVTime getDate (const TableExprId& id) override;
    void clear() override;
  private:
    Vector<MVTime> itsData;
  };
 
 
 
  // <summary>
  // The rowid in a join table
  // </summary>
  // <use visibility=local>
  // <reviewed reviewer="Tammo Jan Dijkema" date="2022/12/15" tests="tTableGramJoin">
  // </reviewed>
  // <synopsis>
  // TaQLJoinRowid contains row sequence numbers of the matching rows
  // in the join table.
  // </synopsis> 
 
  class TaQLJoinRowid : public TableExprNodeRep
  {
  public:
    TaQLJoinRowid (const TableExprInfo&, const TableParseJoin&);
    ~TaQLJoinRowid() override = default;
    TableExprInfo getTableInfo() const override;
    // Get the data (rowid in join table) for the given id.
    // Using the Join object it maps the row number in the main table
    // to the row number in the join table.
    Int64 getInt (const TableExprId& id) override;
  private:
    TableExprInfo         itsTabInfo;
    const TableParseJoin& itsJoin;
  };
 
 
} //# NAMESPACE CASACORE - END
 
#endif