garf-executors 0.2.3__py3-none-any.whl → 1.1.3__py3-none-any.whl

garf/executors/executor.py

@@ -0,0 +1,124 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Defines common functionality between executors."""
+
+import asyncio
+import inspect
+from typing import Optional
+
+from garf.core import report_fetcher
+from garf.executors import execution_context, query_processor
+from garf.executors.telemetry import tracer
+from opentelemetry import trace
+
+
+class Executor:
+  """Defines common functionality between executors."""
+
+  def __init__(
+    self,
+    preprocessors: Optional[dict[str, report_fetcher.Processor]] = None,
+    postprocessors: Optional[dict[str, report_fetcher.Processor]] = None,
+  ) -> None:
+    self.preprocessors = preprocessors or {}
+    self.postprocessors = postprocessors or {}
+
+  @tracer.start_as_current_span('api.execute_batch')
+  def execute_batch(
+    self,
+    batch: dict[str, str],
+    context: execution_context.ExecutionContext,
+    parallel_threshold: int = 10,
+  ) -> list[str]:
+    """Executes batch of queries for a common context.
+
+    If an executor has any pre/post processors, executes them first while
+    modifying the context.
+
+    Args:
+      batch: Mapping between query_title and its text.
+      context: Execution context.
+      parallel_threshold: Number of queries to execute in parallel.
+
+    Returns:
+      Results of execution.
+    """
+    span = trace.get_current_span()
+    span.set_attribute('api.parallel_threshold', parallel_threshold)
+    _handle_processors(processors=self.preprocessors, context=context)
+    results = asyncio.run(
+      self._run(
+        batch=batch, context=context, parallel_threshold=parallel_threshold
+      )
+    )
+    _handle_processors(processors=self.postprocessors, context=context)
+    return results
+
+  def add_preprocessor(
+    self, preprocessors: dict[str, report_fetcher.Processor]
+  ) -> None:
+    self.preprocessors.update(preprocessors)
+
+  async def aexecute(
+    self,
+    query: str,
+    title: str,
+    context: execution_context.ExecutionContext,
+  ) -> str:
+    """Performs query execution asynchronously.
+
+    Args:
+      query: Location of the query.
+      title: Name of the query.
+      context: Query execution context.
+
+    Returns:
+      Result of writing the report.
+    """
+    return await asyncio.to_thread(self.execute, query, title, context)
+
+  async def _run(
+    self,
+    batch: dict[str, str],
+    context: execution_context.ExecutionContext,
+    parallel_threshold: int,
+  ):
+    semaphore = asyncio.Semaphore(value=parallel_threshold)
+
+    async def run_with_semaphore(fn):
+      async with semaphore:
+        return await fn
+
+    tasks = [
+      self.aexecute(query=query, title=title, context=context)
+      for title, query in batch.items()
+    ]
+    return await asyncio.gather(*(run_with_semaphore(task) for task in tasks))
+
+
+def _handle_processors(
+  processors: dict[str, report_fetcher.Processor],
+  context: execution_context.ExecutionContext,
+) -> None:
+  context = query_processor.process_gquery(context)
+  for k, processor in processors.items():
+    processor_signature = list(inspect.signature(processor).parameters.keys())
+    if k in context.fetcher_parameters:
+      processor_parameters = {
+        k: v
+        for k, v in context.fetcher_parameters.items()
+        if k in processor_signature
+      }
+      context.fetcher_parameters[k] = processor(**processor_parameters)

garf/executors/fetchers.py

@@ -0,0 +1,128 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import inspect
+import logging
+import sys
+from importlib.metadata import entry_points
+
+from garf.core import report_fetcher, simulator
+from garf.executors.telemetry import tracer
+
+logger = logging.getLogger(name='garf.executors.fetchers')
+
+
+@tracer.start_as_current_span('find_fetchers')
+def find_fetchers() -> set[str]:
+  """Identifiers all available report fetchers."""
+  if entrypoints := _get_entrypoints('garf'):
+    return {fetcher.name for fetcher in entrypoints}
+  return set()
+
+
+@tracer.start_as_current_span('find_simulators')
+def find_simulators() -> set[str]:
+  """Identifiers all available report simulators."""
+  if entrypoints := _get_entrypoints('garf_simulator'):
+    return {simulator.name for simulator in entrypoints}
+  return set()
+
+
+@tracer.start_as_current_span('get_report_fetcher')
+def get_report_fetcher(source: str) -> type[report_fetcher.ApiReportFetcher]:
+  """Loads report fetcher for a given source.
+
+  Args:
+    source: Alias for a source associated with a fetcher.
+
+  Returns:
+    Class for a found report fetcher.
+
+  Raises:
+    ApiReportFetcherError: When fetcher cannot be loaded.
+    MissingApiReportFetcherError: When fetcher not found.
+  """
+  if source not in find_fetchers():
+    raise report_fetcher.MissingApiReportFetcherError(source)
+  for fetcher in _get_entrypoints('garf'):
+    if fetcher.name == source:
+      try:
+        with tracer.start_as_current_span('load_fetcher_module') as span:
+          fetcher_module = fetcher.load()
+          span.set_attribute('loaded_module', fetcher_module.__name__)
+        for name, obj in inspect.getmembers(fetcher_module):
+          if inspect.isclass(obj) and issubclass(
+            obj, report_fetcher.ApiReportFetcher
+          ):
+            if not hasattr(obj, 'alias'):
+              return getattr(fetcher_module, name)
+            if obj.alias == fetcher.name:
+              return getattr(fetcher_module, name)
+      except ModuleNotFoundError as e:
+        raise report_fetcher.ApiReportFetcherError(
+          f'Failed to load fetcher for source {source}, reason: {e}'
+        )
+  raise report_fetcher.ApiReportFetcherError(
+    f'No fetcher available for the source "{source}"'
+  )
+
+
+@tracer.start_as_current_span('get_report_simulator')
+def get_report_simulator(source: str) -> type[simulator.ApiReportSimulator]:
+  """Loads report simulator for a given source.
+
+  Args:
+    source: Alias for a source associated with a simulator.
+
+  Returns:
+    Class for a found report simulator.
+
+  Raises:
+    GarfApiReportSimulatorError: When simulator cannot be loaded.
+    MissingApiReportSimulatorError: When simulator not found.
+  """
+  if source not in find_simulators():
+    raise simulator.MissingApiReportSimulatorError(source)
+  for sim in _get_entrypoints('garf_simulator'):
+    if sim.name == source:
+      try:
+        with tracer.start_as_current_span('load_simulator_module') as span:
+          simulator_module = sim.load()
+          span.set_attribute('loaded_module', simulator_module.__name__)
+        for name, obj in inspect.getmembers(simulator_module):
+          if inspect.isclass(obj) and issubclass(
+            obj, simulator.ApiReportSimulator
+          ):
+            if not hasattr(obj, 'alias'):
+              return getattr(simulator_module, name)
+            if obj.alias == sim.name:
+              return getattr(simulator_module, name)
+      except ModuleNotFoundError as e:
+        raise simulator.GarfApiReportSimulatorError(
+          f'Failed to load simulator for source {source}, reason: {e}'
+        )
+  raise simulator.GarfApiReportSimulatorError(
+    f'No simulator available for the source "{source}"'
+  )
+
+
+def _get_entrypoints(group='garf'):
+  if sys.version_info.major == 3 and sys.version_info.minor == 9:
+    try:
+      fetchers = entry_points()[group]
+    except KeyError:
+      fetchers = []
+  else:
+    fetchers = entry_points(group=group)
+  return fetchers

garf/executors/garf_pb2.py

@@ -0,0 +1,51 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: garf.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'garf.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.protobuf import struct_pb2 as google_dot_protobuf_dot_struct__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\ngarf.proto\x12\x04garf\x1a\x1cgoogle/protobuf/struct.proto\"a\n\x0c\x46\x65tchRequest\x12\x0e\n\x06source\x18\x01 \x01(\t\x12\r\n\x05title\x18\x02 \x01(\t\x12\r\n\x05query\x18\x03 \x01(\t\x12#\n\x07\x63ontext\x18\x04 \x01(\x0b\x32\x12.garf.FetchContext\"G\n\rFetchResponse\x12\x0f\n\x07\x63olumns\x18\x01 \x03(\t\x12%\n\x04rows\x18\x02 \x03(\x0b\x32\x17.google.protobuf.Struct\"t\n\x0c\x46\x65tchContext\x12/\n\x10query_parameters\x18\x01 \x01(\x0b\x32\x15.garf.QueryParameters\x12\x33\n\x12\x66\x65tcher_parameters\x18\x02 \x01(\x0b\x32\x17.google.protobuf.Struct\"g\n\x0e\x45xecuteRequest\x12\x0e\n\x06source\x18\x01 \x01(\t\x12\r\n\x05title\x18\x02 \x01(\t\x12\r\n\x05query\x18\x03 \x01(\t\x12\'\n\x07\x63ontext\x18\x04 \x01(\x0b\x32\x16.garf.ExecutionContext\"\xbc\x01\n\x10\x45xecutionContext\x12/\n\x10query_parameters\x18\x01 \x01(\x0b\x32\x15.garf.QueryParameters\x12\x33\n\x12\x66\x65tcher_parameters\x18\x02 \x01(\x0b\x32\x17.google.protobuf.Struct\x12\x0e\n\x06writer\x18\x03 \x01(\t\x12\x32\n\x11writer_parameters\x18\x04 \x01(\x0b\x32\x17.google.protobuf.Struct\"d\n\x0fQueryParameters\x12&\n\x05macro\x18\x01 \x01(\x0b\x32\x17.google.protobuf.Struct\x12)\n\x08template\x18\x02 \x01(\x0b\x32\x17.google.protobuf.Struct\"\"\n\x0f\x45xecuteResponse\x12\x0f\n\x07results\x18\x01 \x03(\t2{\n\x0bGarfService\x12\x38\n\x07\x45xecute\x12\x14.garf.ExecuteRequest\x1a\x15.garf.ExecuteResponse\"\x00\x12\x32\n\x05\x46\x65tch\x12\x12.garf.FetchRequest\x1a\x13.garf.FetchResponse\"\x00\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'garf_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_FETCHREQUEST']._serialized_start=50
+  _globals['_FETCHREQUEST']._serialized_end=147
+  _globals['_FETCHRESPONSE']._serialized_start=149
+  _globals['_FETCHRESPONSE']._serialized_end=220
+  _globals['_FETCHCONTEXT']._serialized_start=222
+  _globals['_FETCHCONTEXT']._serialized_end=338
+  _globals['_EXECUTEREQUEST']._serialized_start=340
+  _globals['_EXECUTEREQUEST']._serialized_end=443
+  _globals['_EXECUTIONCONTEXT']._serialized_start=446
+  _globals['_EXECUTIONCONTEXT']._serialized_end=634
+  _globals['_QUERYPARAMETERS']._serialized_start=636
+  _globals['_QUERYPARAMETERS']._serialized_end=736
+  _globals['_EXECUTERESPONSE']._serialized_start=738
+  _globals['_EXECUTERESPONSE']._serialized_end=772
+  _globals['_GARFSERVICE']._serialized_start=774
+  _globals['_GARFSERVICE']._serialized_end=897
+# @@protoc_insertion_point(module_scope)

{garf_executors → garf/executors}/garf_pb2_grpc.py

@@ -5,7 +5,7 @@ import warnings
 
 from . import garf_pb2 as garf__pb2
 
-GRPC_GENERATED_VERSION = '1.75.0'
+GRPC_GENERATED_VERSION = '1.76.0'
 GRPC_VERSION = grpc.__version__
 _version_not_supported = False
 
@@ -18,7 +18,7 @@ except ImportError:
 if _version_not_supported:
     raise RuntimeError(
         f'The grpc package installed is at version {GRPC_VERSION},'
-        + f' but the generated code in garf_pb2_grpc.py depends on'
+        + ' but the generated code in garf_pb2_grpc.py depends on'
         + f' grpcio>={GRPC_GENERATED_VERSION}.'
         + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
         + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
@@ -39,6 +39,11 @@ class GarfServiceStub(object):
                 request_serializer=garf__pb2.ExecuteRequest.SerializeToString,
                 response_deserializer=garf__pb2.ExecuteResponse.FromString,
                 _registered_method=True)
+        self.Fetch = channel.unary_unary(
+                '/garf.GarfService/Fetch',
+                request_serializer=garf__pb2.FetchRequest.SerializeToString,
+                response_deserializer=garf__pb2.FetchResponse.FromString,
+                _registered_method=True)
 
 
 class GarfServiceServicer(object):
@@ -50,6 +55,12 @@ class GarfServiceServicer(object):
         context.set_details('Method not implemented!')
         raise NotImplementedError('Method not implemented!')
 
+    def Fetch(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
 
 def add_GarfServiceServicer_to_server(servicer, server):
     rpc_method_handlers = {
@@ -58,6 +69,11 @@ def add_GarfServiceServicer_to_server(servicer, server):
                     request_deserializer=garf__pb2.ExecuteRequest.FromString,
                     response_serializer=garf__pb2.ExecuteResponse.SerializeToString,
             ),
+            'Fetch': grpc.unary_unary_rpc_method_handler(
+                    servicer.Fetch,
+                    request_deserializer=garf__pb2.FetchRequest.FromString,
+                    response_serializer=garf__pb2.FetchResponse.SerializeToString,
+            ),
     }
     generic_handler = grpc.method_handlers_generic_handler(
             'garf.GarfService', rpc_method_handlers)
@@ -95,3 +111,30 @@ class GarfService(object):
             timeout,
             metadata,
             _registered_method=True)
+
+    @staticmethod
+    def Fetch(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/garf.GarfService/Fetch',
+            garf__pb2.FetchRequest.SerializeToString,
+            garf__pb2.FetchResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

garf/executors/query_processor.py

@@ -0,0 +1,79 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""qQuery can be used as a parameter in garf queries."""
+
+import contextlib
+
+from garf.core import query_editor, query_parser
+from garf.executors import execution_context
+
+
+class GqueryError(query_parser.GarfQueryError):
+  """Errors on incorrect qQuery syntax."""
+
+
+def _handle_sub_context(context, sub_context):
+  for k, v in sub_context.items():
+    if isinstance(v, str) and v.startswith('gquery'):
+      no_writer_context = context.model_copy(update={'writer': None})
+      try:
+        _, alias, *query = v.split(':', maxsplit=3)
+      except ValueError:
+        raise GqueryError(
+          f'Incorrect gquery format, should be gquery:alias:query, got {v}'
+        )
+      if not alias:
+        raise GqueryError(f'Missing alias in gquery: {v}')
+      if not query:
+        raise GqueryError(f'Missing query text in gquery: {v}')
+      if alias == 'sqldb':
+        from garf.executors import sql_executor
+
+        gquery_executor = (
+          sql_executor.SqlAlchemyQueryExecutor.from_connection_string(
+            context.fetcher_parameters.get('connection_string')
+          )
+        )
+      elif alias == 'bq':
+        from garf.executors import bq_executor
+
+        gquery_executor = bq_executor.BigQueryExecutor(
+          **context.fetcher_parameters
+        )
+      else:
+        raise GqueryError(f'Unsupported alias {alias} for gquery: {v}')
+      with contextlib.suppress(
+        query_editor.GarfResourceError, query_parser.GarfVirtualColumnError
+      ):
+        query = ':'.join(query)
+        query_spec = query_editor.QuerySpecification(
+          text=query, args=context.query_parameters
+        ).generate()
+        if len(columns := [c for c in query_spec.column_names if c != '_']) > 1:
+          raise GqueryError(f'Multiple columns in gquery definition: {columns}')
+      res = gquery_executor.execute(
+        query=query, title='gquery', context=no_writer_context
+      )
+      if len(columns := [c for c in res.column_names if c != '_']) > 1:
+        raise GqueryError(f'Multiple columns in gquery result: {columns}')
+      sub_context[k] = res.to_list(row_type='scalar')
+
+
+def process_gquery(
+  context: execution_context.ExecutionContext,
+) -> execution_context.ExecutionContext:
+  _handle_sub_context(context, context.fetcher_parameters)
+  _handle_sub_context(context, context.query_parameters.macro)
+  return context

garf/executors/setup.py

@@ -0,0 +1,58 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Bootstraps executor based on provided parameters."""
+
+from __future__ import annotations
+
+import importlib
+
+from garf.executors import executor, fetchers
+from garf.executors.api_executor import ApiQueryExecutor
+from garf.executors.telemetry import tracer
+
+
+@tracer.start_as_current_span('setup_executor')
+def setup_executor(
+  source: str,
+  fetcher_parameters: dict[str, str | int | bool],
+  enable_cache: bool = False,
+  cache_ttl_seconds: int = 3600,
+  simulate: bool = False,
+) -> type[executor.Executor]:
+  """Initializes executors based on a source and parameters."""
+  if source == 'bq':
+    bq_executor = importlib.import_module('garf.executors.bq_executor')
+    query_executor = bq_executor.BigQueryExecutor(**fetcher_parameters)
+  elif source == 'sqldb':
+    sql_executor = importlib.import_module('garf.executors.sql_executor')
+    query_executor = (
+      sql_executor.SqlAlchemyQueryExecutor.from_connection_string(
+        fetcher_parameters.get('connection_string')
+      )
+    )
+  else:
+    concrete_api_fetcher = fetchers.get_report_fetcher(source)
+    if simulate:
+      concrete_simulator = fetchers.get_report_simulator(source)()
+    else:
+      concrete_simulator = None
+    query_executor = ApiQueryExecutor(
+      fetcher=concrete_api_fetcher(
+        **fetcher_parameters,
+        enable_cache=enable_cache,
+        cache_ttl_seconds=cache_ttl_seconds,
+      ),
+      report_simulator=concrete_simulator,
+    )
+  return query_executor

garf/executors/sql_executor.py

@@ -0,0 +1,144 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Defines mechanism for executing queries via SqlAlchemy."""
+
+from __future__ import annotations
+
+try:
+  import sqlalchemy
+except ImportError as e:
+  raise ImportError(
+    'Please install garf-executors with sqlalchemy support '
+    '- `pip install garf-executors[sqlalchemy]`'
+  ) from e
+
+import logging
+import re
+import uuid
+
+import pandas as pd
+from garf.core import query_editor, report
+from garf.executors import exceptions, execution_context, executor
+from garf.executors.telemetry import tracer
+from opentelemetry import trace
+
+logger = logging.getLogger(__name__)
+
+
+class SqlAlchemyQueryExecutorError(exceptions.GarfExecutorError):
+  """Error when SqlAlchemyQueryExecutor fails to run query."""
+
+
+class SqlAlchemyQueryExecutor(
+  executor.Executor, query_editor.TemplateProcessorMixin
+):
+  """Handles query execution via SqlAlchemy.
+
+  Attributes:
+      engine: Initialized Engine object to operated on a given database.
+  """
+
+  def __init__(
+    self, engine: sqlalchemy.engine.base.Engine | None = None, **kwargs: str
+  ) -> None:
+    """Initializes executor with a given engine.
+
+    Args:
+        engine: Initialized Engine object to operated on a given database.
+    """
+    self.engine = engine or sqlalchemy.create_engine('sqlite://')
+    super().__init__()
+
+  @classmethod
+  def from_connection_string(
+    cls, connection_string: str | None
+  ) -> SqlAlchemyQueryExecutor:
+    """Creates executor from SqlAlchemy connection string.
+
+    https://docs.sqlalchemy.org/en/20/core/engines.html
+    """
+    engine = sqlalchemy.create_engine(connection_string or 'sqlite://')
+    return cls(engine)
+
+  @tracer.start_as_current_span('sql.execute')
+  def execute(
+    self,
+    query: str,
+    title: str,
+    context: execution_context.ExecutionContext = (
+      execution_context.ExecutionContext()
+    ),
+  ) -> report.GarfReport:
+    """Executes query in a given database via SqlAlchemy.
+
+    Args:
+      query: Location of the query.
+      title: Name of the query.
+      context: Query execution context.
+
+    Returns:
+      Report with data if query returns some data otherwise empty Report.
+    """
+    span = trace.get_current_span()
+    span.set_attribute('query.title', title)
+    span.set_attribute('query.text', query)
+    logger.info('Executing script: %s', title)
+    query_text = self.replace_params_template(query, context.query_parameters)
+    with self.engine.begin() as conn:
+      if re.findall(r'(create|update) ', query_text.lower()):
+        try:
+          conn.connection.executescript(query_text)
+          results = report.GarfReport()
+        except Exception as e:
+          raise SqlAlchemyQueryExecutorError(
+            f'Failed to execute query {title}: Reason: {e}'
+          ) from e
+      else:
+        temp_table_name = f'temp_{uuid.uuid4().hex}'
+        query_text = f'CREATE TABLE {temp_table_name} AS {query_text}'
+        conn.connection.executescript(query_text)
+        try:
+          results = report.GarfReport.from_pandas(
+            pd.read_sql(f'SELECT * FROM {temp_table_name}', conn)
+          )
+        except Exception as e:
+          raise SqlAlchemyQueryExecutorError(
+            f'Failed to execute query {title}: Reason: {e}'
+          ) from e
+        finally:
+          conn.connection.execute(f'DROP TABLE {temp_table_name}')
+      if context.writer and results:
+        writer_clients = context.writer_clients
+        if not writer_clients:
+          logger.warning('No writers configured, skipping write operation')
+        else:
+          writing_results = []
+          for writer_client in writer_clients:
+            logger.debug(
+              'Start writing data for query %s via %s writer',
+              title,
+              type(writer_client),
+            )
+            writing_result = writer_client.write(results, title)
+            logger.debug(
+              'Finish writing data for query %s via %s writer',
+              title,
+              type(writer_client),
+            )
+            writing_results.append(writing_result)
+          logger.info('%s executed successfully', title)
+          # Return the last writer's result for backward compatibility
+          return writing_results[-1] if writing_results else None
+      span.set_attribute('execute.num_results', len(results))
+      return results

garf/executors/telemetry.py

@@ -0,0 +1,20 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# pylint: disable=C0330, g-bad-import-order, g-multiple-import
+from opentelemetry import trace
+
+tracer = trace.get_tracer(
+  instrumenting_module_name='garf.executors',
+)