0
# Library Elements
1

2
Management of reusable library panels and variables that can be shared across multiple dashboards. Library elements promote consistency and efficiency by allowing you to create once and reuse across your Grafana instance.
3

4
**Note**: Library elements are only available in Grafana 8.2 and later versions.
5

6
## Capabilities
7

8
### Element Constants
9

10
Library element type constants for creating and filtering elements.
11

12
```python { .api }
13
Panel: int = 1    # Library panel type
14
Variable: int = 2  # Library variable type
15
```
16

17
### Element Retrieval
18

19
Retrieve library elements by identifier, name, or get connection information showing which dashboards use them.
20

21
```python { .api }
22
def get_library_element(self, element_uid: str):
23
    """
24
    Get a library element by its UID.
25
    
26
    Parameters:
27
        element_uid (str): The unique identifier of the library element
28
        
29
    Returns:
30
        dict: Library element data including model and metadata
31
        
32
    Raises:
33
        DeprecationWarning: If Grafana version is earlier than 8.2
34
    """
35

36
def get_library_element_by_name(self, element_name: str):
37
    """
38
    Get a library element by its name.
39
    
40
    Parameters:
41
        element_name (str): The name of the library element
42
        
43
    Returns:
44
        dict: Library element data including model and metadata
45
        
46
    Raises:
47
        DeprecationWarning: If Grafana version is earlier than 8.2
48
    """
49

50
def get_library_element_connections(self, element_uid: str):
51
    """
52
    Get connections showing which dashboards use this library element.
53
    
54
    Parameters:
55
        element_uid (str): The unique identifier of the library element
56
        
57
    Returns:
58
        dict: Connection information with dashboard references
59
        
60
    Raises:
61
        DeprecationWarning: If Grafana version is earlier than 8.2
62
    """
63
```
64

65
### Element Management
66

67
Create, update, and delete library elements with comprehensive configuration options.
68

69
```python { .api }
70
def create_library_element(self, model: dict, name: Optional[str] = None, 
71
                          kind: int = 1, uid: Optional[str] = None, 
72
                          folder_uid: Optional[str] = None):
73
    """
74
    Create a new library element.
75
    
76
    Parameters:
77
        model (dict): The element model (panel or variable configuration)
78
        name (str, optional): Name for the element. Extracted from model if not provided
79
        kind (int): Element type - Panel (1) or Variable (2). Default is Panel
80
        uid (str, optional): Custom UID. Generated if not provided
81
        folder_uid (str, optional): Folder to store element in
82
        
83
    Returns:
84
        dict: Created library element with assigned UID and metadata
85
        
86
    Raises:
87
        DeprecationWarning: If Grafana version is earlier than 8.2
88
    """
89

90
def update_library_element(self, uid: str, model: dict, name: Optional[str] = None, 
91
                          kind: int = 1, folder_uid: Optional[str] = None, 
92
                          version: Optional[int] = None):
93
    """
94
    Update an existing library element.
95
    
96
    Parameters:
97
        uid (str): The UID of the element to update
98
        model (dict): Updated element model
99
        name (str, optional): Updated name
100
        kind (int): Element type - Panel (1) or Variable (2)
101
        folder_uid (str, optional): Move to different folder
102
        version (int, optional): Element version for optimistic locking
103
        
104
    Returns:
105
        dict: Updated library element
106
        
107
    Raises:
108
        DeprecationWarning: If Grafana version is earlier than 8.2
109
        ValueError: If version is required but not provided
110
    """
111

112
def delete_library_element(self, element_uid: str):
113
    """
114
    Delete a library element.
115
    
116
    Parameters:
117
        element_uid (str): The UID of the element to delete
118
        
119
    Returns:
120
        dict: Deletion result
121
        
122
    Raises:
123
        DeprecationWarning: If Grafana version is earlier than 8.2
124
    """
125
```
126

127
### Element Listing and Search
128

129
List and search library elements with comprehensive filtering and pagination options.
130

131
```python { .api }
132
def list_library_elements(self, search_string: Optional[str] = None, 
133
                         kind: Optional[int] = None, sort_direction: Optional[str] = None,
134
                         type_filter: Optional[str] = None, exclude_uid: Optional[str] = None,
135
                         folder_filter: Optional[str] = None, per_page: Optional[int] = None,
136
                         page: Optional[int] = None):
137
    """
138
    List library elements with optional search and filtering.
139
    
140
    Parameters:
141
        search_string (str, optional): Search term for element names
142
        kind (int, optional): Filter by element type (Panel=1, Variable=2)
143
        sort_direction (str, optional): Sort direction ("asc" or "desc")
144
        type_filter (str, optional): Filter by panel type
145
        exclude_uid (str, optional): Exclude element with this UID
146
        folder_filter (str, optional): Filter by folder
147
        per_page (int, optional): Results per page for pagination
148
        page (int, optional): Page number for pagination
149
        
150
    Returns:
151
        dict: List of library elements with pagination metadata
152
        
153
    Raises:
154
        DeprecationWarning: If Grafana version is earlier than 8.2
155
    """
156
```
157

158
## Usage Examples
159

160
### Creating Library Elements
161

162
```python
163
from grafana_client import GrafanaApi, TokenAuth
164

165
# Create API client
166
auth = TokenAuth(token="your-grafana-api-token")
167
api = GrafanaApi(auth=auth, host="your-grafana-host")
168

169
# Create a library panel
170
panel_model = {
171
    "type": "stat",
172
    "title": "Server CPU Usage",
173
    "targets": [
174
        {
175
            "expr": "cpu_usage_percent",
176
            "refId": "A"
177
        }
178
    ],
179
    "fieldConfig": {
180
        "defaults": {
181
            "unit": "percent",
182
            "thresholds": {
183
                "steps": [
184
                    {"color": "green", "value": None},
185
                    {"color": "yellow", "value": 70},
186
                    {"color": "red", "value": 90}
187
                ]
188
            }
189
        }
190
    }
191
}
192

193
# Create the library panel
194
library_panel = api.libraryelement.create_library_element(
195
    model=panel_model,
196
    name="CPU Usage Panel",
197
    kind=api.libraryelement.Panel,
198
    folder_uid="monitoring-folder-uid"
199
)
200

201
print(f"Created library panel: {library_panel['uid']}")
202

203
# Create a library variable
204
variable_model = {
205
    "type": "query",
206
    "name": "server",
207
    "label": "Server",
208
    "query": "label_values(up, instance)",
209
    "multi": True,
210
    "includeAll": True
211
}
212

213
library_variable = api.libraryelement.create_library_element(
214
    model=variable_model,
215
    name="Server Selection Variable",
216
    kind=api.libraryelement.Variable
217
)
218

219
print(f"Created library variable: {library_variable['uid']}")
220
```
221

222
### Managing Library Elements
223

224
```python
225
# List all library panels
226
panels = api.libraryelement.list_library_elements(
227
    kind=api.libraryelement.Panel,
228
    sort_direction="asc"
229
)
230

231
for panel in panels['elements']:
232
    print(f"Panel: {panel['name']} - UID: {panel['uid']}")
233

234
# Search for CPU-related elements
235
cpu_elements = api.libraryelement.list_library_elements(
236
    search_string="CPU",
237
    per_page=10,
238
    page=1
239
)
240

241
# Get specific library element
242
element_uid = "library-panel-uid"
243
element = api.libraryelement.get_library_element(element_uid)
244
print(f"Element: {element['name']} - Type: {element['kind']}")
245

246
# Check which dashboards use this element
247
connections = api.libraryelement.get_library_element_connections(element_uid)
248
for connection in connections:
249
    print(f"Used in dashboard: {connection['connectionUid']}")
250

251
# Update library element
252
updated_model = element['model']
253
updated_model['title'] = "Updated CPU Usage Panel"
254

255
api.libraryelement.update_library_element(
256
    uid=element_uid,
257
    model=updated_model,
258
    name="Updated CPU Usage Panel"
259
)
260

261
# Delete library element (only if not in use)
262
api.libraryelement.delete_library_element(element_uid)
263
print("Library element deleted")
264
```
265

266
### Working with Library Variables
267

268
```python
269
# Create a complex library variable
270
datasource_variable = {
271
    "type": "datasource",
272
    "name": "datasource",
273
    "label": "Data Source",
274
    "query": "prometheus",
275
    "multi": False,
276
    "includeAll": False,
277
    "current": {
278
        "value": "prometheus-uid",
279
        "text": "Prometheus"
280
    }
281
}
282

283
library_var = api.libraryelement.create_library_element(
284
    model=datasource_variable,
285
    name="Prometheus Datasource Variable",
286
    kind=api.libraryelement.Variable,
287
    folder_uid="variables-folder"
288
)
289

290
# List only library variables
291
variables = api.libraryelement.list_library_elements(
292
    kind=api.libraryelement.Variable
293
)
294

295
for var in variables['elements']:
296
    print(f"Variable: {var['name']} - Type: {var['model']['type']}")
297
```