.. _querying_gateway:


****************
Querying Gateway
****************

digital-world-py-sdk gives you access to all the endpoints exposed by Gateway.

Building requests
=================

digital-world-py-sdk uses the `Builder pattern <https://en.wikipedia.org/wiki/Builder_pattern>`_ to create the requests to send
to Gateway. Starting with a :py:class:`GatewayServer <digital_world_sdk.server.GatewayServer>` object, you can chain methods together to generate a query.
(See the `Gateway reference <https://docs.digitalworld.global/api/>`_ documentation for what methods are possible.)

.. literalinclude:: ../../../examples/query_gateway.py
   :language: python
   :linenos:

Once the request is built, it can be invoked with :py:meth:`call() <digital_world_sdk.call_builder.BaseCallBuilder.call>` or
with :py:meth:`stream() <digital_world_sdk.call_builder.BaseCallBuilder.stream>`.
:py:meth:`call() <digital_world_sdk.call_builder.BaseCallBuilder.call>` will return the
response given by Gateway.

Streaming requests
==================

Many requests can be invoked with :py:meth:`stream() <digital_world_sdk.call_builder.BaseCallBuilder.stream>`.
Instead of returning a result like :py:meth:`call() <digital_world_sdk.call_builder.BaseCallBuilder.call>` does,
:py:meth:`stream() <digital_world_sdk.call_builder.BaseCallBuilder.stream>` will return an EventSource.
Gateway will start sending responses from either the beginning of time or from the point
specified with :py:meth:`cursor() <digital_world_sdk.call_builder.BaseCallBuilder.cursor>`.
(See the `Gateway reference <https://docs.digitalworld.global/api/>`_ documentation to learn which endpoints support streaming.)

For example, to log instances of transactions from a particular account:

.. literalinclude:: ../../../examples/stream_requests.py
   :language: python
   :linenos: