Skip to content

ResultSet

influxdb.resultset

Module to prepare the resultset.

Classes

ResultSet

Bases: object

A wrapper around a single InfluxDB query result.

Source code in influxdb/resultset.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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
class ResultSet(object):
    """A wrapper around a single InfluxDB query result."""

    def __init__(self, series, raise_errors=True):
        """Initialize the ResultSet.

        Args:
            series (dict): the series data from InfluxDB
            raise_errors (bool): whether to raise exceptions on errors, defaults to True

        """
        self._raw = series
        self._error = self._raw.get("error", None)

        if self.error is not None and raise_errors is True:
            raise InfluxDBClientError(self.error)

    @property
    def raw(self):
        """Raw JSON from InfluxDB."""
        return self._raw

    @raw.setter
    def raw(self, value):
        self._raw = value

    @property
    def error(self):
        """Error returned by InfluxDB."""
        return self._error

    def __getitem__(self, key):
        """Retrieve the series name or specific set based on key.

        Args:
            key: Either a series name, or a tags_dict, or a 2-tuple(series_name, tags_dict).
                If the series name is None (or not given) then any serie
                matching the eventual given tags will be given its points
                one after the other.
                To get the points of every series in this resultset then
                you have to provide None as key.

        Returns:
            generator: A generator yielding Points matching the given key.

        Note:
            ResultSet's __getitem__ method will be deprecated. Use get_points instead.
            The order in which the points are yielded is actually undefined but it might change.

        """
        warnings.warn(
            ("ResultSet's ``__getitem__`` method will be deprecated. Use``get_points`` instead."),
            DeprecationWarning,
            stacklevel=2,
        )

        if isinstance(key, tuple):
            if len(key) != 2:
                raise TypeError("only 2-tuples allowed")

            name = key[0]
            tags = key[1]

            if not isinstance(tags, dict) and tags is not None:
                raise TypeError("tags should be a dict")
        elif isinstance(key, dict):
            name = None
            tags = key
        else:
            name = key
            tags = None

        return self.get_points(name, tags)

    def get_points(self, measurement=None, tags=None):
        """Return a generator for all the points that match the given filters.

        Args:
            measurement (str): The measurement name
            tags (dict): Tags to look for

        Returns:
            generator: Points generator

        Raises:
            TypeError: if measurement is not str or None

        """
        # Raise error if measurement is not str or bytes
        if not isinstance(measurement, (bytes, type(b"".decode()), type(None))):
            raise TypeError("measurement must be an str or None")

        for series in self._get_series():
            series_name = series.get("measurement", series.get("name", "results"))
            if series_name is None:
                # this is a "system" query or a query which
                # doesn't return a name attribute.
                # like 'show retention policies' ..
                if tags is None:
                    for item in self._get_points_for_series(series):
                        yield item

            elif measurement in (None, series_name):
                # by default if no tags was provided then
                # we will matches every returned series
                series_tags = series.get("tags", {})
                for item in self._get_points_for_series(series):
                    if tags is None or self._tag_matches(item, tags) or self._tag_matches(series_tags, tags):
                        yield item

    def __repr__(self):
        """Representation of ResultSet object."""
        items = []

        for item in self.items():
            items.append("'%s': %s" % (item[0], list(item[1])))

        return "ResultSet({%s})" % ", ".join(items)

    def __iter__(self):
        """Yield one dict instance per series result."""
        for key in self.keys():
            yield list(self.__getitem__(key))

    @staticmethod
    def _tag_matches(tags, filter):
        """Check if all key/values in filter match in tags."""
        for tag_name, tag_value in filter.items():
            # using _sentinel as I'm not sure that "None"
            # could be used, because it could be a valid
            # series_tags value : when a series has no such tag
            # then I think it's set to /null/None/.. TBC..
            series_tag_value = tags.get(tag_name, _sentinel)
            if series_tag_value != tag_value:
                return False

        return True

    def _get_series(self):
        """Return all series."""
        return self.raw.get("series", [])

    def __len__(self):
        """Return the len of the keys in the ResultSet."""
        return len(self.keys())

    def keys(self):
        """Return the list of keys in the ResultSet.

        Returns:
            list: List of keys. Keys are tuples (series_name, tags)

        """
        keys = []
        for series in self._get_series():
            keys.append(
                (
                    series.get("measurement", series.get("name", "results")),
                    series.get("tags", None),
                )
            )
        return keys

    def items(self):
        """Return the set of items from the ResultSet.

        Returns:
            list: List of tuples, (key, generator)

        """
        items = []
        for series in self._get_series():
            series_key = (
                series.get("measurement", series.get("name", "results")),
                series.get("tags", None),
            )
            items.append((series_key, self._get_points_for_series(series)))
        return items

    def _get_points_for_series(self, series):
        """Return generator of dict from columns and values of a series.

        Args:
            series (dict): One series

        Returns:
            generator: Generator of dicts

        """
        for point in series.get("values", []):
            yield self.point_from_cols_vals(series["columns"], point)

    @staticmethod
    def point_from_cols_vals(cols, vals):
        """Create a dict from columns and values lists.

        Args:
            cols (list): List of columns
            vals (list): List of values

        Returns:
            dict: Dict where keys are columns.

        """
        point = {}
        for col_index, col_name in enumerate(cols):
            point[col_name] = vals[col_index]

        return point
Attributes
raw property writable

Raw JSON from InfluxDB.

error property

Error returned by InfluxDB.

Functions
__init__(series, raise_errors=True)

Initialize the ResultSet.

Parameters:

Name Type Description Default
series dict

the series data from InfluxDB

 required
raise_errors bool

whether to raise exceptions on errors, defaults to True

 True
Source code in influxdb/resultset.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
def __init__(self, series, raise_errors=True):
    """Initialize the ResultSet.

    Args:
        series (dict): the series data from InfluxDB
        raise_errors (bool): whether to raise exceptions on errors, defaults to True

    """
    self._raw = series
    self._error = self._raw.get("error", None)

    if self.error is not None and raise_errors is True:
        raise InfluxDBClientError(self.error)
__getitem__(key)

Retrieve the series name or specific set based on key.

Parameters:

Name Type Description Default
key

Either a series name, or a tags_dict, or a 2-tuple(series_name, tags_dict). If the series name is None (or not given) then any serie matching the eventual given tags will be given its points one after the other. To get the points of every series in this resultset then you have to provide None as key.

 required

Returns:

Name Type Description
generator

A generator yielding Points matching the given key.
Note

ResultSet's getitem method will be deprecated. Use get_points instead. The order in which the points are yielded is actually undefined but it might change.

Source code in influxdb/resultset.py 
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
def __getitem__(self, key):
    """Retrieve the series name or specific set based on key.

    Args:
        key: Either a series name, or a tags_dict, or a 2-tuple(series_name, tags_dict).
            If the series name is None (or not given) then any serie
            matching the eventual given tags will be given its points
            one after the other.
            To get the points of every series in this resultset then
            you have to provide None as key.

    Returns:
        generator: A generator yielding Points matching the given key.

    Note:
        ResultSet's __getitem__ method will be deprecated. Use get_points instead.
        The order in which the points are yielded is actually undefined but it might change.

    """
    warnings.warn(
        ("ResultSet's ``__getitem__`` method will be deprecated. Use``get_points`` instead."),
        DeprecationWarning,
        stacklevel=2,
    )

    if isinstance(key, tuple):
        if len(key) != 2:
            raise TypeError("only 2-tuples allowed")

        name = key[0]
        tags = key[1]

        if not isinstance(tags, dict) and tags is not None:
            raise TypeError("tags should be a dict")
    elif isinstance(key, dict):
        name = None
        tags = key
    else:
        name = key
        tags = None

    return self.get_points(name, tags)
get_points(measurement=None, tags=None)

Return a generator for all the points that match the given filters.

Parameters:

Name Type Description Default
measurement str

The measurement name

 None
tags dict

Tags to look for

 None

Returns:

Name Type Description
generator

Points generator

Raises:

Type Description
TypeError

if measurement is not str or None
Source code in influxdb/resultset.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
def get_points(self, measurement=None, tags=None):
    """Return a generator for all the points that match the given filters.

    Args:
        measurement (str): The measurement name
        tags (dict): Tags to look for

    Returns:
        generator: Points generator

    Raises:
        TypeError: if measurement is not str or None

    """
    # Raise error if measurement is not str or bytes
    if not isinstance(measurement, (bytes, type(b"".decode()), type(None))):
        raise TypeError("measurement must be an str or None")

    for series in self._get_series():
        series_name = series.get("measurement", series.get("name", "results"))
        if series_name is None:
            # this is a "system" query or a query which
            # doesn't return a name attribute.
            # like 'show retention policies' ..
            if tags is None:
                for item in self._get_points_for_series(series):
                    yield item

        elif measurement in (None, series_name):
            # by default if no tags was provided then
            # we will matches every returned series
            series_tags = series.get("tags", {})
            for item in self._get_points_for_series(series):
                if tags is None or self._tag_matches(item, tags) or self._tag_matches(series_tags, tags):
                    yield item
__repr__()

Representation of ResultSet object.

Source code in influxdb/resultset.py 
126
127
128
129
130
131
132
133
def __repr__(self):
    """Representation of ResultSet object."""
    items = []

    for item in self.items():
        items.append("'%s': %s" % (item[0], list(item[1])))

    return "ResultSet({%s})" % ", ".join(items)
__iter__()

Yield one dict instance per series result.

Source code in influxdb/resultset.py 
135
136
137
138
def __iter__(self):
    """Yield one dict instance per series result."""
    for key in self.keys():
        yield list(self.__getitem__(key))
__len__()

Return the len of the keys in the ResultSet.

Source code in influxdb/resultset.py 
158
159
160
def __len__(self):
    """Return the len of the keys in the ResultSet."""
    return len(self.keys())
keys()

Return the list of keys in the ResultSet.

Returns:

Name Type Description
list

List of keys. Keys are tuples (series_name, tags)
Source code in influxdb/resultset.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
def keys(self):
    """Return the list of keys in the ResultSet.

    Returns:
        list: List of keys. Keys are tuples (series_name, tags)

    """
    keys = []
    for series in self._get_series():
        keys.append(
            (
                series.get("measurement", series.get("name", "results")),
                series.get("tags", None),
            )
        )
    return keys
items()

Return the set of items from the ResultSet.

Returns:

Name Type Description
list

List of tuples, (key, generator)
Source code in influxdb/resultset.py 
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
def items(self):
    """Return the set of items from the ResultSet.

    Returns:
        list: List of tuples, (key, generator)

    """
    items = []
    for series in self._get_series():
        series_key = (
            series.get("measurement", series.get("name", "results")),
            series.get("tags", None),
        )
        items.append((series_key, self._get_points_for_series(series)))
    return items
point_from_cols_vals(cols, vals) staticmethod

Create a dict from columns and values lists.

Parameters:

Name Type Description Default
cols list

List of columns

 required
vals list

List of values

 required

Returns:

Name Type Description
dict

Dict where keys are columns.
Source code in influxdb/resultset.py 
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
@staticmethod
def point_from_cols_vals(cols, vals):
    """Create a dict from columns and values lists.

    Args:
        cols (list): List of columns
        vals (list): List of values

    Returns:
        dict: Dict where keys are columns.

    """
    point = {}
    for col_index, col_name in enumerate(cols):
        point[col_name] = vals[col_index]

    return point