Skip to content

plpipes.database.backend#

Module for defining the database backend interface in the plpipes framework.

This module provides the Backend class, which serves as an abstraction layer for different database backends. It allows interaction with various data representations such as pandas, geopandas, Spark DataFrames, polars, and more.

Classes:

Name Description
Backend

The base class for database backends providing methods for executing queries, handling data chunking, grouping results, and retrieving first results.

Backend #

Bases: Plugin

Abstract base class for database backends.

This class defines the interface for various database backends that can perform queries and manage data representations.

Methods:

Name Description
query

Executes a query and returns the result.
query_chunked

Executes a chunked query and returns results.
query_group

Executes a grouped query and returns results.
query_first

Executes a query and returns the first result.
query_first_value

Executes a query and returns the first value.
Source code in src\plpipes\database\backend\__init__.py 
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
class Backend(Plugin):
    """
    Abstract base class for database backends.

    This class defines the interface for various database backends that can
    perform queries and manage data representations.

    Methods:
        query(engine, sql, parameters, kws): Executes a query and returns the result.
        query_chunked(engine, sql, parameter, kws): Executes a chunked query and returns results.
        query_group(engine, sql, parameters, by, kws): Executes a grouped query and returns results.
        query_first(engine, sql, parameters, kws): Executes a query and returns the first result.
        query_first_value(engine, sql, parameters, kws): Executes a query and returns the first value.
    """

    def query(self, engine, sql, parameters, kws):
        """
        Executes a query against the database.

        Args:
            engine (object): The database engine to use for executing the query.
            sql (str): The SQL query to execute.
            parameters (dict): Optional parameters for the SQL query.
            kws (dict): Additional keyword arguments for the execution.

        Raises:
            NotImplementedError: This method must be implemented in subclasses.
        """
        raise NotImplementedError("This function is not yet implemented.")

    def query_chunked(self, engine, sql, parameters, kws):
        """
        Executes a chunked query against the database.

        Args:
            engine (object): The database engine to use for executing the query.
            sql (str): The SQL query to execute.
            parameters (dict): Optional parameters for the SQL query.
            kws (dict): Additional keyword arguments for the execution.

        Raises:
            NotImplementedError: This method must be implemented in subclasses.
        """
        raise NotImplementedError("This function is not yet implemented.")

    def query_group(self, engine, sql, parameters, by, kws):
        """
        Executes a grouped query against the database.

        Args:
            engine (object): The database engine to use for executing the query.
            sql (str): The SQL query to execute.
            parameters (dict): Optional parameters for the SQL query.
            by (str): The column(s) to group the results by.
            kws (dict): Additional keyword arguments for the execution.

        Raises:
            NotImplementedError: This method must be implemented in subclasses.
        """
        raise NotImplementedError("This function is not yet implemented.")

    def query_first(self, engine, sql, parameters, kws):
        """
        Executes a query and retrieves the first result.

        Args:
            engine (object): The database engine to use for executing the query.
            sql (str): The SQL query to execute.
            parameters (dict): Optional parameters for the SQL query.
            kws (dict): Additional keyword arguments for the execution.

        Raises:
            NotImplementedError: This method must be implemented in subclasses.
        """
        raise NotImplementedError("This function is not yet implemented.")

    def query_first_value(self, engine, sql, parameters, kws):
        """
        Executes a query and retrieves the first value from the result.

        Args:
            engine (object): The database engine to use for executing the query.
            sql (str): The SQL query to execute.
            parameters (dict): Optional parameters for the SQL query.
            kws (dict): Additional keyword arguments for the execution.

        Raises:
            NotImplementedError: This method must be implemented in subclasses.
        """
        raise NotImplementedError("This function is not yet implemented.")

query(engine, sql, parameters, kws) #

Executes a query against the database.

Parameters:

Name Type Description Default
engine object

The database engine to use for executing the query.

 required
sql str

The SQL query to execute.

 required
parameters dict

Optional parameters for the SQL query.

 required
kws dict

Additional keyword arguments for the execution.

 required

Raises:

Type Description
NotImplementedError

This method must be implemented in subclasses.
Source code in src\plpipes\database\backend\__init__.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def query(self, engine, sql, parameters, kws):
    """
    Executes a query against the database.

    Args:
        engine (object): The database engine to use for executing the query.
        sql (str): The SQL query to execute.
        parameters (dict): Optional parameters for the SQL query.
        kws (dict): Additional keyword arguments for the execution.

    Raises:
        NotImplementedError: This method must be implemented in subclasses.
    """
    raise NotImplementedError("This function is not yet implemented.")

query_chunked(engine, sql, parameters, kws) #

Executes a chunked query against the database.

Parameters:

Name Type Description Default
engine object

The database engine to use for executing the query.

 required
sql str

The SQL query to execute.

 required
parameters dict

Optional parameters for the SQL query.

 required
kws dict

Additional keyword arguments for the execution.

 required

Raises:

Type Description
NotImplementedError

This method must be implemented in subclasses.
Source code in src\plpipes\database\backend\__init__.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def query_chunked(self, engine, sql, parameters, kws):
    """
    Executes a chunked query against the database.

    Args:
        engine (object): The database engine to use for executing the query.
        sql (str): The SQL query to execute.
        parameters (dict): Optional parameters for the SQL query.
        kws (dict): Additional keyword arguments for the execution.

    Raises:
        NotImplementedError: This method must be implemented in subclasses.
    """
    raise NotImplementedError("This function is not yet implemented.")

query_first(engine, sql, parameters, kws) #

Executes a query and retrieves the first result.

Parameters:

Name Type Description Default
engine object

The database engine to use for executing the query.

 required
sql str

The SQL query to execute.

 required
parameters dict

Optional parameters for the SQL query.

 required
kws dict

Additional keyword arguments for the execution.

 required

Raises:

Type Description
NotImplementedError

This method must be implemented in subclasses.
Source code in src\plpipes\database\backend\__init__.py 
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def query_first(self, engine, sql, parameters, kws):
    """
    Executes a query and retrieves the first result.

    Args:
        engine (object): The database engine to use for executing the query.
        sql (str): The SQL query to execute.
        parameters (dict): Optional parameters for the SQL query.
        kws (dict): Additional keyword arguments for the execution.

    Raises:
        NotImplementedError: This method must be implemented in subclasses.
    """
    raise NotImplementedError("This function is not yet implemented.")

query_first_value(engine, sql, parameters, kws) #

Executes a query and retrieves the first value from the result.

Parameters:

Name Type Description Default
engine object

The database engine to use for executing the query.

 required
sql str

The SQL query to execute.

 required
parameters dict

Optional parameters for the SQL query.

 required
kws dict

Additional keyword arguments for the execution.

 required

Raises:

Type Description
NotImplementedError

This method must be implemented in subclasses.
Source code in src\plpipes\database\backend\__init__.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def query_first_value(self, engine, sql, parameters, kws):
    """
    Executes a query and retrieves the first value from the result.

    Args:
        engine (object): The database engine to use for executing the query.
        sql (str): The SQL query to execute.
        parameters (dict): Optional parameters for the SQL query.
        kws (dict): Additional keyword arguments for the execution.

    Raises:
        NotImplementedError: This method must be implemented in subclasses.
    """
    raise NotImplementedError("This function is not yet implemented.")

query_group(engine, sql, parameters, by, kws) #

Executes a grouped query against the database.

Parameters:

Name Type Description Default
engine object

The database engine to use for executing the query.

 required
sql str

The SQL query to execute.

 required
parameters dict

Optional parameters for the SQL query.

 required
by str

The column(s) to group the results by.

 required
kws dict

Additional keyword arguments for the execution.

 required

Raises:

Type Description
NotImplementedError

This method must be implemented in subclasses.
Source code in src\plpipes\database\backend\__init__.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
def query_group(self, engine, sql, parameters, by, kws):
    """
    Executes a grouped query against the database.

    Args:
        engine (object): The database engine to use for executing the query.
        sql (str): The SQL query to execute.
        parameters (dict): Optional parameters for the SQL query.
        by (str): The column(s) to group the results by.
        kws (dict): Additional keyword arguments for the execution.

    Raises:
        NotImplementedError: This method must be implemented in subclasses.
    """
    raise NotImplementedError("This function is not yet implemented.")