0
# Data Examples
1

2
Normalized data formats for representing training examples, feature vectors, and structured data inputs for machine learning models. These types are essential for data preprocessing, model training, and inference workflows.
3

4
## Capabilities
5

6
### Example
7

8
The primary data structure for representing training/inference examples with named features.
9

10
```java { .api }
11
/**
12
 * Normalized data format for training/inference examples
13
 */
14
class Example {
15
  /** Get the features map */
16
  Features getFeatures();
17
  
18
  /** Create a new builder for constructing Example */
19
  static Builder newBuilder();
20
  
21
  /** Builder for constructing Example instances */
22
  static class Builder {
23
    Builder setFeatures(Features features);
24
    Example build();
25
  }
26
}
27
```
28

29
**Usage Examples:**
30

31
```java
32
import org.tensorflow.example.*;
33

34
// Create a simple example with numeric and string features
35
Example userExample = Example.newBuilder()
36
    .setFeatures(Features.newBuilder()
37
        .putFeature("age", Feature.newBuilder()
38
            .setInt64List(Int64List.newBuilder().addValue(25))
39
            .build())
40
        .putFeature("height", Feature.newBuilder()
41
            .setFloatList(FloatList.newBuilder().addValue(175.5f))
42
            .build())
43
        .putFeature("name", Feature.newBuilder()
44
            .setBytesList(BytesList.newBuilder()
45
                .addValue(ByteString.copyFromUtf8("Alice")))
46
            .build())
47
        .putFeature("interests", Feature.newBuilder()
48
            .setBytesList(BytesList.newBuilder()
49
                .addValue(ByteString.copyFromUtf8("reading"))
50
                .addValue(ByteString.copyFromUtf8("hiking"))
51
                .addValue(ByteString.copyFromUtf8("coding")))
52
            .build()))
53
    .build();
54

55
// Create an image classification example
56
Example imageExample = Example.newBuilder()
57
    .setFeatures(Features.newBuilder()
58
        .putFeature("image_raw", Feature.newBuilder()
59
            .setBytesList(BytesList.newBuilder()
60
                .addValue(ByteString.copyFrom(imageBytes)))
61
            .build())
62
        .putFeature("label", Feature.newBuilder()
63
            .setInt64List(Int64List.newBuilder().addValue(7))  // digit 7
64
            .build())
65
        .putFeature("height", Feature.newBuilder()
66
            .setInt64List(Int64List.newBuilder().addValue(28))
67
            .build())
68
        .putFeature("width", Feature.newBuilder()
69
            .setInt64List(Int64List.newBuilder().addValue(28))
70
            .build()))
71
    .build();
72
```
73

74
### SequenceExample
75

76
Example representing sequences with context features (time-independent) and sequence features (time-dependent).
77

78
```java { .api }
79
/**
80
 * Example representing sequences with context and sequence features
81
 */
82
class SequenceExample {
83
  /** Get time-independent context features */
84
  Features getContext();
85
  
86
  /** Get sequence features (time-dependent) */
87
  FeatureLists getFeatureLists();
88
  
89
  /** Create a new builder for constructing SequenceExample */
90
  static Builder newBuilder();
91
  
92
  /** Builder for constructing SequenceExample instances */
93
  static class Builder {
94
    Builder setContext(Features context);
95
    Builder setFeatureLists(FeatureLists featureLists);
96
    SequenceExample build();
97
  }
98
}
99
```
100

101
**Usage Examples:**
102

103
```java
104
import org.tensorflow.example.*;
105

106
// Create a sequence example for text processing
107
SequenceExample textSequence = SequenceExample.newBuilder()
108
    .setContext(Features.newBuilder()
109
        .putFeature("document_id", Feature.newBuilder()
110
            .setBytesList(BytesList.newBuilder()
111
                .addValue(ByteString.copyFromUtf8("doc_123")))
112
            .build())
113
        .putFeature("language", Feature.newBuilder()
114
            .setBytesList(BytesList.newBuilder()
115
                .addValue(ByteString.copyFromUtf8("en")))
116
            .build()))
117
    .setFeatureLists(FeatureLists.newBuilder()
118
        .putFeatureList("tokens", FeatureList.newBuilder()
119
            .addFeature(Feature.newBuilder()
120
                .setBytesList(BytesList.newBuilder()
121
                    .addValue(ByteString.copyFromUtf8("hello")))
122
                .build())
123
            .addFeature(Feature.newBuilder()
124
                .setBytesList(BytesList.newBuilder()
125
                    .addValue(ByteString.copyFromUtf8("world")))
126
                .build())
127
            .build())
128
        .putFeatureList("pos_tags", FeatureList.newBuilder()
129
            .addFeature(Feature.newBuilder()
130
                .setBytesList(BytesList.newBuilder()
131
                    .addValue(ByteString.copyFromUtf8("INTJ")))
132
                .build())
133
            .addFeature(Feature.newBuilder()
134
                .setBytesList(BytesList.newBuilder()
135
                    .addValue(ByteString.copyFromUtf8("NOUN")))
136
                .build())
137
            .build()))
138
    .build();
139

140
// Create a time series example
141
SequenceExample timeSeriesExample = SequenceExample.newBuilder()
142
    .setContext(Features.newBuilder()
143
        .putFeature("series_id", Feature.newBuilder()
144
            .setBytesList(BytesList.newBuilder()
145
                .addValue(ByteString.copyFromUtf8("sensor_001")))
146
            .build())
147
        .putFeature("location", Feature.newBuilder()
148
            .setBytesList(BytesList.newBuilder()
149
                .addValue(ByteString.copyFromUtf8("building_A")))
150
            .build()))
151
    .setFeatureLists(FeatureLists.newBuilder()
152
        .putFeatureList("temperature", FeatureList.newBuilder()
153
            .addFeature(Feature.newBuilder()
154
                .setFloatList(FloatList.newBuilder().addValue(20.1f))
155
                .build())
156
            .addFeature(Feature.newBuilder()
157
                .setFloatList(FloatList.newBuilder().addValue(20.3f))
158
                .build())
159
            .addFeature(Feature.newBuilder()
160
                .setFloatList(FloatList.newBuilder().addValue(20.0f))
161
                .build())
162
            .build())
163
        .putFeatureList("timestamp", FeatureList.newBuilder()
164
            .addFeature(Feature.newBuilder()
165
                .setInt64List(Int64List.newBuilder().addValue(1634567890))
166
                .build())
167
            .addFeature(Feature.newBuilder()
168
                .setInt64List(Int64List.newBuilder().addValue(1634567950))
169
                .build())
170
            .addFeature(Feature.newBuilder()
171
                .setInt64List(Int64List.newBuilder().addValue(1634568010))
172
                .build())
173
            .build()))
174
    .build();
175
```
176

177
### Feature
178

179
Individual feature containing typed data (bytes, floats, or integers).
180

181
```java { .api }
182
/**
183
 * Individual feature containing typed data
184
 */
185
class Feature {
186
  /** Get list of byte string values */
187
  BytesList getBytesList();
188
  
189
  /** Get list of float values */
190
  FloatList getFloatList();
191
  
192
  /** Get list of integer values */
193
  Int64List getInt64List();
194
  
195
  /** Get which kind of value is set */
196
  KindCase getKindCase();
197
  
198
  /** Create a new builder for constructing Feature */
199
  static Builder newBuilder();
200
  
201
  /** Builder for constructing Feature instances */
202
  static class Builder {
203
    Builder setBytesList(BytesList bytesList);
204
    Builder setFloatList(FloatList floatList);
205
    Builder setInt64List(Int64List int64List);
206
    Feature build();
207
  }
208
  
209
  /** Enum indicating which value type is set */
210
  enum KindCase {
211
    BYTES_LIST,
212
    FLOAT_LIST,
213
    INT64_LIST,
214
    KIND_NOT_SET
215
  }
216
}
217
```
218

219
### BytesList, FloatList, Int64List
220

221
Typed lists for different data types within features.
222

223
```java { .api }
224
/**
225
 * List of byte string values
226
 */
227
class BytesList {
228
  List<ByteString> getValueList();
229
  
230
  static Builder newBuilder();
231
  
232
  static class Builder {
233
    Builder addValue(ByteString value);
234
    Builder addAllValue(Iterable<ByteString> values);
235
    BytesList build();
236
  }
237
}
238

239
/**
240
 * List of float values
241
 */
242
class FloatList {
243
  List<Float> getValueList();
244
  
245
  static Builder newBuilder();
246
  
247
  static class Builder {
248
    Builder addValue(float value);
249
    Builder addAllValue(Iterable<Float> values);
250
    FloatList build();
251
  }
252
}
253

254
/**
255
 * List of 64-bit integer values
256
 */
257
class Int64List {
258
  List<Long> getValueList();
259
  
260
  static Builder newBuilder();
261
  
262
  static class Builder {
263
    Builder addValue(long value);
264
    Builder addAllValue(Iterable<Long> values);
265
    Int64List build();
266
  }
267
}
268
```
269

270
### Features
271

272
Map from feature name to Feature objects.
273

274
```java { .api }
275
/**
276
 * Map from feature name to Feature
277
 */
278
class Features {
279
  /** Get feature name to Feature mapping */
280
  Map<String, Feature> getFeatureMap();
281
  
282
  /** Create a new builder for constructing Features */
283
  static Builder newBuilder();
284
  
285
  /** Builder for constructing Features instances */
286
  static class Builder {
287
    Builder putFeature(String key, Feature value);
288
    Builder putAllFeature(Map<String, Feature> features);
289
    Features build();
290
  }
291
}
292
```
293

294
### FeatureLists and FeatureList
295

296
For sequence examples, these represent time-series or sequential features.
297

298
```java { .api }
299
/**
300
 * Map from feature list name to FeatureList
301
 */
302
class FeatureLists {
303
  /** Get feature list name to FeatureList mapping */
304
  Map<String, FeatureList> getFeatureListMap();
305
  
306
  /** Create a new builder for constructing FeatureLists */
307
  static Builder newBuilder();
308
  
309
  /** Builder for constructing FeatureLists instances */
310
  static class Builder {
311
    Builder putFeatureList(String key, FeatureList value);
312
    Builder putAllFeatureList(Map<String, FeatureList> featureLists);
313
    FeatureLists build();
314
  }
315
}
316

317
/**
318
 * Sequence of features for time-series data
319
 */
320
class FeatureList {
321
  /** Get list of features in sequence */
322
  List<Feature> getFeatureList();
323
  
324
  /** Create a new builder for constructing FeatureList */
325
  static Builder newBuilder();
326
  
327
  /** Builder for constructing FeatureList instances */
328
  static class Builder {
329
    Builder addFeature(Feature feature);
330
    Builder addAllFeature(Iterable<Feature> features);
331
    FeatureList build();
332
  }
333
}
334
```
335

336
### ExampleParserConfiguration
337

338
Configuration for parsing Example protos efficiently.
339

340
```java { .api }
341
/**
342
 * Configuration for parsing Example protos
343
 */
344
class ExampleParserConfiguration {
345
  Map<String, FeatureConfiguration> getFeatureMapMap();
346
  
347
  /**
348
   * Configuration for individual features
349
   */
350
  static class FeatureConfiguration {
351
    ConfigCase getConfigCase();
352
    FixedLenFeature getFixedLenFeature();
353
    VarLenFeature getVarLenFeature();
354
    
355
    enum ConfigCase {
356
      FIXED_LEN_FEATURE,
357
      VAR_LEN_FEATURE,
358
      CONFIG_NOT_SET
359
    }
360
  }
361
  
362
  /**
363
   * Configuration for fixed-length features
364
   */
365
  static class FixedLenFeature {
366
    List<Long> getShapeList();
367
    DataType getDtype();
368
    TensorProto getDefaultValue();
369
  }
370
  
371
  /**
372
   * Configuration for variable-length features
373
   */
374
  static class VarLenFeature {
375
    DataType getDtype();
376
  }
377
}
378
```
379

380
**Usage Examples:**
381

382
```java
383
import org.tensorflow.example.*;
384

385
// Working with different feature types
386
Feature stringFeature = Feature.newBuilder()
387
    .setBytesList(BytesList.newBuilder()
388
        .addValue(ByteString.copyFromUtf8("category_a"))
389
        .addValue(ByteString.copyFromUtf8("category_b")))
390
    .build();
391

392
Feature numericFeature = Feature.newBuilder()
393
    .setFloatList(FloatList.newBuilder()
394
        .addValue(1.5f)
395
        .addValue(2.3f)
396
        .addValue(0.8f))
397
    .build();
398

399
Feature idFeature = Feature.newBuilder()
400
    .setInt64List(Int64List.newBuilder()
401
        .addValue(12345L))
402
    .build();
403

404
// Check feature type
405
switch (feature.getKindCase()) {
406
    case BYTES_LIST:
407
        List<ByteString> strings = feature.getBytesList().getValueList();
408
        break;
409
    case FLOAT_LIST:
410
        List<Float> floats = feature.getFloatList().getValueList();
411
        break;
412
    case INT64_LIST:
413
        List<Long> integers = feature.getInt64List().getValueList();
414
        break;
415
    case KIND_NOT_SET:
416
        // Handle empty feature
417
        break;
418
}
419
```