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/user_guides/fs/feature_view/feature-vectors.md
+91-21
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ Once you have trained a model, it is time to deploy it. You can get back all the
4
4
If you want to understand more about the concept of feature vectors, you can refer to [here](../../../concepts/fs/feature_view/online_api.md).
5
5
6
6
## Retrieval
7
-
You can get back feature vectors from either python or java client by providing the primary key value(s) for the feature view. Note that filters defined in feature view and training data will not be applied when feature vectors are returned.
7
+
You can get back feature vectors from either python or java client by providing the primary key value(s) for the feature view. Note that filters defined in feature view and training data will not be applied when feature vectors are returned. If you need to retrieve a complete value of feature vectors without missing values, the required `entry` are [feature_view.primary_keys](https://docs.hopsworks.ai/feature-store-api/3.7/generated/api/feature_view_api/#primary_keys). Alternative, you can provide the primary key of the feature groups as the key of the entry. It is also possible to provide a subset of the entry, which will be discussed [below](#partial-feature-retrieval).
8
8
9
9
=== "Python"
10
10
```python
@@ -37,48 +37,118 @@ You can get back feature vectors from either python or java client by providing
Starting from python client v3.4, you can specify different values for the primary key of the same name which exists in multiple feature groups but are not joint by the same name. The table below summarises the value of `primary_keys` in different settings. Considering that you are joining 2 feature groups, namely, `left_fg` and `right_fg`, the feature groups have different primary keys, and features (`feature_*`) in each setting. Also, the 2 feature groups are [joint](https://docs.hopsworks.ai/feature-store-api/3.7/generated/api/query_api/#join) on different *join conditions* and *prefix* as `left_fg.join(right_fg, <join conditions>, prefix=<prefix>)`.
42
+
43
+
For java client, and python client before v3.4, the `primary_keys` are the set of primary key of all the feature groups in the query. Python client is backward compatible. It means that the `primary_keys` used before v3.4 can be applied to python client of later versions as well.
44
+
45
+
| Setting | primary key of `left_fg`| primary key of `right_fg`| join conditions | prefix | primary_keys | note |
| 1 | id | id |```on=["id"]```|| id | Same feature name is used in the join. |
48
+
| 2 | id1 | id2 |`left_on=["id1"], right_on=["id2"]`|| id1 | Different feature names are used in the join. |
49
+
| 3 | id1, id2 | id1 |`on=["id1"]`|| id1, id2 |`id2` is not part of the join conditions |
50
+
| 4 | id, user_id | id |`left_on=["user_id"], right_on=["id"]`|| id, user_id | Value of `user_id` is used for retrieving features from `right_fg`|
51
+
| 5 | id1 | id1, id2 |`on=["id1"]`|| id1, id2 |`id2` is not part of the join conditions |
52
+
| 6 | id | id, user_id |`left_on=["id"], right_on=["user_id"]`| “right_“| id, “right_id“ | Value of “right_id“ and "id" are used for retrieving features from `right_fg`|
53
+
| 7 | id | id, user_id |`left_on=["id"], right_on=["user_id"]`|| id, “fgId_<rightFgId>_<joinIndex>_id” | Value of “fgId_<rightFgId>_<joinIndex>_id“ and "id" are used for retrieving features from `right_fg`. See note below. |
54
+
| 8 | id | id |`left_on=["id"], right_on=["feature_1"]`| “right_“ | id, “right_id“ | No primary key from `right_fg` is used in the join. Value of `right_id` is used for retrieving features from `right_fg`|
55
+
| 9 | id | id |`left_on=["id"], right_on=["feature_1"]`|| id1, “fgId_<rightFgId>_<joinIndex>_id” | No primary key from `right_fg` is used in the join. Value of "fgId_<rightFgId>_<joinIndex>_id" is used for retrieving features from "right_fg`. See note below. |
56
+
| 10 | id | id |`left_on=["feature_1"], right_on=["id"]`| “right_“ | id, “right_id“ | No primary key from `left_fg` is used in the join. Value of `right_id` is used for retrieving features from `right_fg`|
57
+
| 11 | id | id |`left_on=["feature_1"], right_on=["id"]`|| id1, “fgId_<rightFgId>_<joinIndex>_id” | No primary key from `left_fg` is used in the join. Value of “fgId_<rightFgId>_<joinIndex>_id” is used for retrieving features from `right_fg`. See note below. |
58
+
| 12 | user, year | user, year |`left_on=["user"], right_on=["user"]`| “right_“ | user, year, “right_year“ | Value of "user" and "right_year" are used for retrieving features from `right_fg`. `right_fg` can be the same as feature group as `left_fg`. |
59
+
| 13 | user, year | user, year |`left_on=["user"], right_on=["user"]`|| user, year, “fgId_<rightFgId>_<joinIndex>_year” | Value of "user" and "fgId_<rightFgId>_<joinIndex>_year" are used for retrieving features from `right_fg`. `right_fg` can be the same as feature group as `left_fg`. See note below. |
60
+
61
+
Note:
62
+
63
+
"<rightFgId>" can be found by `right_fg.id`. "<joinIndex>" is the order or the feature group in the join. In the example, it is 1 because `right_fg` is in the first join in the query `left_fg.join(right_fg, <join conditions>)`.
64
+
40
65
### Missing Primary Key Entries
41
66
42
67
It can happen that some of the primary key entries are not available in some or all of the feature groups used by a feature view.
43
68
44
69
Take the above example assuming the feature view consists of two joined feature groups, first one with primary key column `pk1`, the second feature group with primary key column `pk2`.
45
-
```python
46
-
# get a single vector
47
-
feature_view.get_feature_vector(
48
-
entry= {"pk1": 1, "pk2": 2}
49
-
)
50
-
```
70
+
=== "Python"
71
+
```python
72
+
# get a single vector
73
+
feature_view.get_feature_vector(
74
+
entry = {"pk1": 1, "pk2": 2}
75
+
)
76
+
```
77
+
=== "Java"
78
+
```java
79
+
// get a single vector
80
+
Map<String, Object> entry1 = Maps.newHashMap();
81
+
entry1.put("pk1", 1);
82
+
entry1.put("pk2", 2);
83
+
featureView.getFeatureVector(entry1);
84
+
```
51
85
This call will raise an exception if `pk1 = 1` OR `pk2 = 2` can't be found but also if `pk1 = 1` AND `pk2 = 2` can't be found, meaning, it will not return a partial or empty feature vector.
52
86
53
87
When retrieving a batch of vectors, the behaviour is slightly different.
This call will raise an exception if for example for the third entry `pk1 = 5` OR `pk2 = 6` can't be found, however, it will simply not return a vector for this entry if `pk1 = 5` AND `pk2 = 6`
65
111
can't be found.
66
112
That means, `get_feature_vectors` will never return partial feature vector, but will omit empty feature vectors.
67
113
68
-
If you are aware of missing featurs, you can use the [*passed features*](#passed-features) functionality, described down below.
114
+
If you are aware of missing features, you can use the [*passed features*](#passed-features) or [Partial feature retrieval](#partial-feature-retrieval) functionality, described down below.
115
+
116
+
### Partial feature retrieval
117
+
If your model can handle missing value or if you want to impute the missing value, you can get back feature vectors with partial values using python client starting from version 3.4 (Note that this does not apply to java client.). In the example below, let's say you join 2 feature groups by `fg1.join(fg2, left_on=["pk1"], right_on=["pk2"])`, required keys of the `entry` are `pk1` and `pk2`. If `pk2` is not provided, this returns feature values from the first feature group and null values from the second feature group when using the option `allow_missing=True`, otherwise it raises exception.
118
+
119
+
=== "Python"
120
+
```python
121
+
# get a single vector with
122
+
feature_view.get_feature_vector(
123
+
entry = {"pk1": 1},
124
+
allow_missing=True
125
+
)
126
+
127
+
# get multiple vectors
128
+
feature_view.get_feature_vectors(
129
+
entry = [
130
+
{"pk1": 1},
131
+
{"pk1": 3},
132
+
],
133
+
allow_missing=True
134
+
)
135
+
```
69
136
70
137
### Retrieval with transformation
71
138
If you have specified transformation functions when creating a feature view, you receive transformed feature vectors. If your transformation functions require statistics of training dataset, you must also provide the training data version. `init_serving` will then fetch the statistics and initialize the functions with the required statistics. Then you can follow the above examples and retrieve the feature vectors. Please note that transformed feature vectors can only be returned in the python client but not in the java client.
If some of the features values are only known at prediction time and cannot be computed and cached in the online feature store, you can provide those values as `passed_features` option. The `get_feature_vector` method is going to use the passed values to construct the final feature vector to submit to the model.
79
147
80
148
You can use the `passed_features` parameter to overwrite individual features being retrieved from the online feature store. The feature view will apply the necessary transformations to the passed features as it does for the feature data retrieved from the online feature store.
81
149
150
+
Please note that passed features is only available in the python client but not in the java client.
0 commit comments