You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/docs/python-sdk/guides/store.mdx
+59-52Lines changed: 59 additions & 52 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,175 +6,182 @@ import TabItem from '@theme/TabItem';
6
6
7
7
# Using the client store
8
8
9
-
The client in the SDK contains a store object that is used to store Nodes in a local cache.
9
+
The client in the SDK contains a store that is used to store objects in a local cache.
10
10
11
-
The store is mainly used for the internal working of the SDK. It is used to create relations between nodes that might not yet exist in the database, or to store relations for nodes that were retrieved from the database, amongst other things.
11
+
The store is mainly used for the internal working of the SDK. It is used to create relations between objects that might not yet exist in the database, or to store relations for objects that were retrieved from the database, amongst other things.
12
12
13
-
The store can also be used to store Nodes that we retrieve using the client query methods. This allows to not have to keep references to nodes we retrieved throughout scripts, or avoids situations where we have to redo queries to retrieve nodes.
13
+
The store stores objects that we are retrieving from Infrahub using the different query methods. This allows to not have to keep references to objects throughout scripts, or avoids situations where we have to re-execute queries.
14
14
15
-
## Storing nodes in the store
15
+
Objects are stored in the following scenario:
16
16
17
-
Nodes retrieved from Infrahub using a the SDK client's query methods, such as the `get``filters` or `all`method, will be automatically stored in the internal store. Nodes stored in the store using this method can be retrieved using their `id` as the key in the store.
17
+
- The resulting objects from using the SDK client's `get`,`filters` or `all`methods
18
18
19
19
<TabsgroupId="async-sync">
20
20
<TabItemvalue="Async"default>
21
21
22
22
```python
23
23
tag =await client.get(kind="BuiltinTag", name__value="RED")
24
+
tag_in_store = client.store.get(key=tag.id)
24
25
```
25
26
26
27
</TabItem>
27
28
<TabItemvalue="Sync"default>
28
29
29
30
```python
30
31
tag = client.get(kind="BuiltinTag", name__value="RED")
32
+
tag_in_store = client.store.get(key=tag.id)
31
33
```
32
34
33
35
</TabItem>
34
36
</Tabs>
35
37
36
-
This behaviour may not be desirable in all scenarios, therefor you can explicitly disable this behaviour by setting the `populate_store` argument to `False` when calling the query methods.
38
+
- The resulting related objects for objects retrieved using the SDK client's query methods, when we use the `prefetch_relationships` argument.
37
39
38
40
<TabsgroupId="async-sync">
39
41
<TabItemvalue="Async"default>
40
42
41
43
```python
42
-
tag =await client.get(kind="BuiltinTag", name__value="RED", populate_store=False)
You can store nodes in the object store manually using the `set` method. This has the advantage that you can choose which key you use to reference the node in the store. For example, we could use the name attribute value of the node as the key.
59
+
- The related objects of a object's relationship when the `fetch` method is used
58
60
59
61
<TabsgroupId="async-sync">
60
62
<TabItemvalue="Async"default>
61
63
62
64
```python
63
-
tag =await client.get(kind="BuiltinTag", name__value="RED", populate_store=False)
Nodes can be retrieved from the internal store using the key that was used to store them.
81
-
For nodes that are stored by the client's query methods, this will be their `id`.
82
+
- Objects that get created using the SDK
82
83
83
84
<TabsgroupId="async-sync">
84
85
<TabItemvalue="Async"default>
85
86
86
87
```python
87
-
tag =await client.get(kind="BuiltinTag", name__value="RED")
88
+
tag =await client.create("BuiltinTag", name="BLACK")
89
+
await tag.save()
88
90
tag_in_store = client.store.get(key=tag.id)
89
-
assert tag == tag_in_store
90
91
```
91
92
92
93
</TabItem>
93
94
<TabItemvalue="Sync"default>
94
95
95
96
```python
96
-
tag = client.get(kind="BuiltinTag", name__value="RED")
97
+
tag = client.create("BuiltinTag", name="BLACK")
98
+
tag.save()
97
99
tag_in_store = client.store.get(key=tag.id)
98
-
assert tag == tag_in_store
99
100
```
100
101
101
102
</TabItem>
102
103
</Tabs>
103
104
104
-
For nodes that have been added manually to the store, this will be the key that you specified when storing the node. For example, when you used the name attribute value of the node you can use that name to retrieve the node from the store.
105
+
## Retrieving objects from the store
106
+
107
+
You can retrieve objects from the store using their `id` or `hfid`. When using the `hfid`, we also have to provide the `kind` of the object that we want to retrieve.
105
108
106
109
<TabsgroupId="async-sync">
107
110
<TabItemvalue="Async"default>
108
111
109
112
```python
110
-
tag =await client.get(kind="BuiltinTag", name__value="RED", populate_store=False)
When you are using the internal store, you can use the `prefect_relationships` argument in all the client query methods. All the related nodes, for the relationships that are in scope of the query will be retrieved using this option. This has the advantage that you don't have to `fetch` related node(s) for a relation manually, but it comes at the cost of a more complex query, which might have an impact on the performance of the query.
140
+
You can store objects in the store manually using the `set` method. This has the advantage that you can choose a key that you want to use to reference the object in the store, besides the `id` or `hfid`. For example, we could use the name attribute value of the node as the key.
## Disable storing objects in the store using the different query methods
153
170
154
-
You can use a custom store, outside of the Infrahub SDK client. Storing or retrieving nodes works exactly the same as for the internal store. The advantage is that you are in full control of the contents of the store.
171
+
In some scenarios it might not be desirable to automatically store the retrieved objects in the store, when using the SDK client's different query methods. In this case you can set the `populate_store` argument to `False`.
0 commit comments