class_docstr: Abstraction for querying databases with user-supplied connection objects.
class_docstr_tok: ["Abstraction","for","querying","databases","with","user-supplied","connection","objects","."]
docstr: Execute a query and reference the result set.
docstr_tok: ["Execute","a","query","and","reference","the","result","set","."]
code: def execute(
      self,
      query: str | Selectable,
      *,
      options: dict[str, Any] | None = None,
      select_queries_only: bool = True,
  ) -> Self:
      """Execute a query and reference the result set."""
      if select_queries_only and isinstance(query, str):
          q = re.search(
              r"\w{3,}", re.sub(r"/\*(.|[\r\n])*?\*/", "", query)
          )
          if (
              query_type := "" if not q else q.group(0)
          ) in _INVALID_QUERY_TYPES:
              raise UnsuitableSQLError(
                  f"{query_type} statements are not valid 'read' queries"
              )
  
      options = options or {}
      cursor_execute = self.cursor.execute
  
      if self.driver_name == "sqlalchemy" and isinstance(query, str):
          params = options.get("parameters")
          if isinstance(params, Sequence) and hasattr(
              self.cursor, "exec_driver_sql"
          ):
              cursor_execute = self.cursor.exec_driver_sql
              if isinstance(params, list) and not all(
                  isinstance(p, (dict, tuple)) for p in params
              ):
                  options["parameters"] = tuple(params)
          else:
              from sqlalchemy.sql import text
  
              query = text(query)  # type: ignore[assignment]
  
      # note: some cursor execute methods (eg: sqlite3) only take positional
      # params, hence the slightly convoluted resolution of the 'options' dict
      try:
          params = signature(cursor_execute).parameters
      except ValueError:
          params = {}
  
      if not options or any(
          p.kind
          in (Parameter.KEYWORD_ONLY, Parameter.POSITIONAL_OR_KEYWORD)
          for p in params.values()
      ):
          result = cursor_execute(query, **options)
      else:
          positional_options = (
              options[o]
              for o in (params or options)
              if (not options or o in options)
          )
          result = cursor_execute(query, *positional_options)
  
      # note: some cursors execute in-place
      result = self.cursor if result is None else result
      self.result = result
      return self
  
imports: from __future__ import annotations
  import re
  import sys
  from importlib import import_module
  from inspect import Parameter, signature
  from typing import TYPE_CHECKING, Any, Iterable, Literal, Sequence, TypedDict, overload
  from polars.convert import from_arrow
  from polars.exceptions import InvalidOperationError, UnsuitableSQLError
  from polars.utils.deprecation import issue_deprecation_warning
label_desc: Use image node_id 11 for calling the ConnectionExecutor obj's underlying member method code with example usage: obj.execute(query) and returns: self