SQL query result. More...

#include <sql_result.h>

Inheritance diagram for hazelcast::client::sql::sql_result:

Classes
class	page_iterator
	Copy is allowed for convenience but it does shallow copy so it should be avoided. More...
class	page_iterator_sync
	Copy is allowed for convenience but it does shallow copy so it should be avoided. More...
class	row_iterator_sync
	Copy is allowed for convenience but it does shallow copy so it should be avoided. More...

Public Member Functions
virtual	~sql_result ()
	The destructor closes the result if it were open.
bool	row_set () const
	Return whether this result has rows to iterate using the iterator() method.
const sql_row_metadata &	row_metadata () const
	Gets the row metadata.
int64_t	update_count () const
	Returns the number of rows updated by the statement or -1 if this result is a row set.
boost::future< void >	close ()
	Release the resources associated with the query result.
page_iterator	iterator ()
	Returns an iterator over the result pages.
page_iterator_sync	pbegin (std::chrono::milliseconds timeout=std::chrono::milliseconds{ -1 })
page_iterator_sync	pend ()
row_iterator_sync	begin (std::chrono::milliseconds timeout=std::chrono::milliseconds{ -1 })
row_iterator_sync	end ()

Friends
class	sql_service

Detailed Description

SQL query result.

Depending on the statement type it represents a pages of rows or an update count.

Usage for page of rows

Use iterator() to iterate the pages. see page_iterator
Use close() to release the resources associated with the result.

Code example:

  auto result = hz.get_sql().execute("SELECT * FROM person");
  for (auto itr = result.iterator(); itr.has_next();) {
     auto page = itr.next().get();

     for (auto const &row : page->rows()) {
        // Process the row.
     }
  }

Usage for update count

     auto updated = hz.get_sql().execute("UPDATE ...").get().update_count();

You don't need to call close() in this case.

Definition at line 67 of file sql_result.h.

Constructor & Destructor Documentation

◆ ~sql_result()

hazelcast::client::sql::sql_result::~sql_result ( )

virtual

The destructor closes the result if it were open.

Definition at line 955 of file sql.cpp.

{
    try {
        close().get();
    } catch (...) {
        // ignore
        HZ_LOG(client_context_->get_logger(),
               info,
               (boost::format("[sql_result::~sql_result()] Exception while "
                              "closing the query result. Query id: %1%") %
                query_id_)
                 .str());
    }
}

Member Function Documentation

◆ begin()

sql_result::row_iterator_sync hazelcast::client::sql::sql_result::begin ( std::chrono::milliseconds timeout = std::chrono::milliseconds{ -1 } )

Definition at line 815 of file sql.cpp.

{
    return row_iterator_sync{ pbegin(timeout) };
}

◆ close()

boost::future< void > hazelcast::client::sql::sql_result::close ( )

Release the resources associated with the query result.

The query engine delivers the rows asynchronously. The query may become inactive even before all rows are consumed. The invocation of this command will cancel the execution of the query on all members if the query is still active. Otherwise it is no-op. For a result with an update count it is always no-op.

Definition at line 901 of file sql.cpp.

{
    if (closed_) {
        return boost::make_ready_future();
    }
 
    auto release_resources = [this]() {
        {
            std::lock_guard<std::mutex> guard{ mtx_ };
            closed_ = true;
 
            connection_.reset();
        }
 
        row_metadata_.reset();
        first_page_.reset();
    };
 
    try {
        auto f = service_->close(connection_, query_id_);
 
        release_resources();
 
        return f;
    } catch (const std::exception& e) {
        release_resources();
 
        service_->rethrow(e);
    }
 
    // This should not be reached.
    return boost::make_ready_future();
}

◆ end()

sql_result::row_iterator_sync hazelcast::client::sql::sql_result::end ( )

Definition at line 821 of file sql.cpp.

{
    return row_iterator_sync{};
}

◆ iterator()

sql_result::page_iterator hazelcast::client::sql::sql_result::iterator ( )

Returns an iterator over the result pages.

The iterator may be requested only once.

Returns: the iterator to be used over the result. The iterator iterates page by page over the result.

Exceptions

exception::illegal_state if the iterator is requested more than once or if this result does not have any pages.

Definition at line 783 of file sql.cpp.

{
    check_closed();
 
    if (!first_page_) {
        BOOST_THROW_EXCEPTION(exception::illegal_state(
          "sql_result::iterator", "This result contains only update count"));
    }
 
    if (iterator_requested_) {
        BOOST_THROW_EXCEPTION(exception::illegal_state(
          "sql_result::page_iterator", "Iterator can be requested only once"));
    }
 
    iterator_requested_ = true;
 
    return { shared_from_this(), first_page_ };
}

◆ pbegin()

sql_result::page_iterator_sync hazelcast::client::sql::sql_result::pbegin ( std::chrono::milliseconds timeout = std::chrono::milliseconds{ -1 } )

Definition at line 803 of file sql.cpp.

{
    return page_iterator_sync{ iterator(), timeout };
}

◆ pend()

sql_result::page_iterator_sync hazelcast::client::sql::sql_result::pend ( )

Definition at line 809 of file sql.cpp.

{
    return page_iterator_sync{};
}

◆ row_metadata()

const sql_row_metadata & hazelcast::client::sql::sql_result::row_metadata ( ) const

Gets the row metadata.

Returns: the metadata of the rows in this result.

Exceptions

illegal_state_exception if this result doesn't have rows, but only an update count

Definition at line 945 of file sql.cpp.

{
    if (!row_metadata_) {
        throw exception::illegal_state(
          "sql_result::row_metadata", "This result contains only update count");
    }
 
    return *row_metadata_;
}

◆ row_set()

bool hazelcast::client::sql::sql_result::row_set ( ) const

Return whether this result has rows to iterate using the iterator() method.

Definition at line 777 of file sql.cpp.

{
    return update_count() == -1;
}

◆ update_count()

int64_t hazelcast::client::sql::sql_result::update_count ( ) const

Returns the number of rows updated by the statement or -1 if this result is a row set.

In case the result doesn't contain rows but the update count isn't applicable or known, 0 is returned.

Definition at line 771 of file sql.cpp.

{
    return update_count_;
}

◆ sql_service

friend class sql_service

friend

Definition at line 308 of file sql_result.h.

The documentation for this class was generated from the following files:

hazelcast/include/hazelcast/client/sql/sql_result.h
hazelcast/src/hazelcast/client/sql.cpp

Classes

Public Member Functions

Friends