Add reference documentation #46

dixonjoel · 2025-10-15T19:02:04Z

What does this Pull Request accomplish?

Adds documentation about the data and metadata store entities with real-world examples. Also adds a 'workflow' document on how the NI Measurement Data Services can be used.

Why should this Pull Request be merged?

First pass at some docs to help customers with general understanding.

What testing has been done?

Just docs build and PR.

Copilot

Pull Request Overview

This PR adds comprehensive reference documentation for the NI Measurement Data Services, including entity definitions, workflow guidance, and example links. The documentation covers the complete measurement data lifecycle from setup through analysis.

Key changes include:

Added detailed entity reference documentation for both metadata and data stores
Created a comprehensive workflow guide showing typical usage patterns
Integrated example notebook links into the documentation structure

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/reference/using-measurement-data-services.md	Complete workflow documentation covering setup, test execution, and analysis phases
docs/reference/ni-metadata-store.md	Entity reference for metadata store components (operators, hardware, UUTs, etc.)
docs/reference/ni-data-store.md	Entity reference for data store components (test results, measurements, conditions)
docs/reference/index.rst	Reference section index page
docs/examples/index.rst	Examples section with links to Jupyter notebooks
docs/index.rst	Updated main index to include new reference and examples sections
docs/conf.py	Added Jupyter checkpoint exclusion pattern

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-15T19:02:36Z

docs/reference/ni-metadata-store.md

@@ -0,0 +1,389 @@
+# NI Metadata Store
+
+The NI Metadata Store support the digital thread weaving together measurement results with metadata that describes **who**, **what**, **where**, and **how** tests are performed. This creates a complete context around your test data, enabling traceability and analysis across your entire test ecosystem.


Corrected verb agreement: 'support' should be 'supports' to match the singular subject 'NI Metadata Store'.

Suggested change

The NI Metadata Store support the digital thread weaving together measurement results with metadata that describes **who**, **what**, **where**, and **how** tests are performed. This creates a complete context around your test data, enabling traceability and analysis across your entire test ecosystem.

The NI Metadata Store supports the digital thread weaving together measurement results with metadata that describes **who**, **what**, **where**, and **how** tests are performed. This creates a complete context around your test data, enabling traceability and analysis across your entire test ecosystem.

Copilot · 2025-10-15T19:02:36Z

docs/reference/using-measurement-data-services.md

+```python
+# Find measurements from specific equipment that failed
+equipment_failures = data_store_client.query_measurements(
+    f"$filter=outcome eq 'OUTCOME_FAILED' and contains(hardware_item_ids, '{dmm_id}')"


The OData query syntax may be incorrect for array field queries. The 'contains' function typically requires the field name as the second parameter and the value as the first parameter, or may not work with array fields depending on the OData implementation.

Suggested change

f"$filter=outcome eq 'OUTCOME_FAILED' and contains(hardware_item_ids, '{dmm_id}')"

f"$filter=outcome eq 'OUTCOME_FAILED' and hardware_item_ids/any(id: id eq '{dmm_id}')"

dixonjoel · 2025-10-15T19:08:39Z

@nick-beer @ccifra I wanted y'all to take a look at these. They are mostly AI-generated as a first pass. Please review for general content, direction, terminology, accuracy etc. For the most part, the documentation for metadata store and data store are not Python-specific. The one about using NI MDS has some Python API calling code but that could be more pseudo-code if we want to generalize this documentation and use it for something not specific to LV or Python, i.e. conceptual documentation.

…rence-documentation

hunter-ni · 2025-10-17T20:28:05Z

docs/reference/ni-metadata-store.md

+id = "https://example.com/scope.schema.toml"
+
+[hardware_item]
+bandwidth = "*"           # Required field - must be provided


I don't believe the use of ? here is supported.

* indicates that any value is acceptable for the extension property. Whether or not an extension property is required is specified using the required key.

[hardware_item] bandwidth = "*" manufacture_date = "*" required = ["bandwidth"]

Is there any documentation of this format? Or do you know where I can look in the code to see what the schema schema is?

DataStoreMetadataProviderTestStateBase may be a helpful reference point, in terms of both showing an example schema (both TOML and JSON) and in programmatically building a TOML schema string. sample_schema.json in the current repo is also a pretty representative example of a JSON schema.

hunter-ni · 2025-10-17T20:29:03Z

docs/reference/ni-metadata-store.md

+**Field Requirement Indicators:**
+- `"*"` = **Required** - Must be provided when creating the entity
+- `"?"` = **Optional** - Can be provided but not mandatory
+- Additional validation rules can be specified in JSON Schema format


I believe there should be parity between the TOML and JSON formats, so I'm not clear on what this means.

hunter-ni · 2025-10-17T20:34:06Z

docs/reference/using-measurement-data-services.md

+    family="Power",
+    manufacturers=["ACME Corp"],
+    part_number="PS-v2.1-001",
+    extensions={


I believe we need to specify a schema_id if we are specifying extension values. Similar comment elsewhere above and below.

hunter-ni · 2025-10-17T20:35:57Z

docs/reference/using-measurement-data-services.md

+data_store_client.publish_condition(
+    condition_name="Temperature",
+    type="Environment",
+    value=23.5,  # °C


[Consider] We could show how to use Scalar to ensure that the unit information is published as well?

hunter-ni · 2025-10-17T20:39:00Z

docs/reference/using-measurement-data-services.md

+)
+```
+
+#### **Batch Measurements** *(For Parametric Sweeps)*


I think we need to be careful here to indicate that the non-batched publish RPCs can also be used for parametric sweeps -- the decision about whether to use batching is more about when you are doing the publishing -- as you go (non-batched) or all at once, sometime later (batched).

hunter-ni · 2025-10-17T20:41:22Z

docs/reference/using-measurement-data-services.md

+```python
+# Update test result with final outcome
+test_result = data_store_client.get_test_result(test_result_id)
+test_result.end_date_time = datetime.now()


I don't believe these are values that we expect the client to set, but perhaps @nick-beer can confirm.

hunter-ni · 2025-10-17T20:44:21Z

docs/reference/using-measurement-data-services.md

+    f"$filter=contains(test_result_id, '{test_result_id}')"
+)
+
+# Find tests by operator


This looks like it is just retrieving the operator itself--not finding tests.

hunter-ni · 2025-10-17T20:46:18Z

docs/reference/using-measurement-data-services.md

+
+#### **Test Results Analysis**
+```python
+# Find all test results for a UUT model


I don't think a UUT model is factoring in here(?)

hunter-ni · 2025-10-17T20:51:05Z

docs/reference/using-measurement-data-services.md

+#### **Equipment Usage Tracking**
+```python
+# Find all hardware items due for calibration
+equipment_due = metadata_store_client.query_hardware_items(


CalibrationDueDate is currently a free text field, so I don't think that this sort of lt comparison would be expected to work(?)

Thinking about the HardwareItem information tracked by the metadata store more broadly, it essentially provides snapshots of the state of a given hardware item at a given point in time, so I don't think a question about the current state of the hardware is well-suited to be answered by a query like this.

hunter-ni · 2025-10-17T20:54:24Z

docs/reference/using-measurement-data-services.md

+```python
+# Track performance over time for a UUT model
+uut_instances = metadata_store_client.query_uut_instances(
+    f"$filter=uut_id eq '{power_supply_uut_id}'"


Broad comment about the OData filter queries: I don't think that they use the _ naming convention. (UutId instead of uut_id.)

hunter-ni · 2025-10-17T21:18:47Z

docs/reference/ni-metadata-store.md

+
+```python
+# 1. Register the schema
+schema_content = load_schema_from_file("scope_schema.toml")


Maybe just use metadata_store_client.register_schema_from_file here instead(?)

hunter-ni · 2025-10-17T21:25:43Z

docs/reference/using-measurement-data-services.md

+#### **UUT (Product Definitions)**
+```python
+# Define the product being tested
+power_supply_uut_id = metadata_store_client.create_uut(UUT(


The expected capitalization is Uut and UutInstance. That should be reflected in these examples.

hunter-ni · 2025-10-17T21:31:18Z

docs/reference/using-measurement-data-services.md

+```python
+# Create aliases for easy reference
+metadata_store_client.create_alias(Alias(
+    alias_name="Primary_DMM",


create_alias takes an alias_name and alias_target, rather than an Alias.

hunter-ni · 2025-10-17T21:41:15Z

docs/reference/using-measurement-data-services.md

+```python
+# Get measurement data using moniker
+for measurement in measurements:
+    if measurement.data_type == "Scalar":


I believe the actual type that is returned here is more fully qualified--can you confirm?

Thinking more about this particular example, we should probably change it so that we read back Vector, since single Scalar values aren't read back from the service in isolation.

hunter-ni · 2025-10-17T21:47:19Z

docs/reference/using-measurement-data-services.md

+Access the actual measured values:
+
+```python
+# Get measurement data using moniker


[Optional] We are indeed using the Moniker under the hood, but from the client's perspective, the Moniker is never directly referenced here. With that in mind, we could update this documentation/comment to reflect that.

hunter-ni · 2025-10-17T21:51:57Z

docs/examples/index.rst

+
+* `publish_measurement.ipynb <https://github.com/ni/datastore-python/blob/main/examples/notebooks/overview/publish_measurement.ipynb>`_ - Basic measurement publishing
+* `alias.ipynb <https://github.com/ni/datastore-python/blob/main/examples/notebooks/alias/alias.ipynb>`_ - Working with aliases
+* `custom_metadata.ipynb <https://github.com/ni/datastore-python/blob/main/examples/notebooks/custom-metadata/custom_metadata.ipynb>`_ - Custom metadata examples


[Minor] We should probably move in the direction of referring to these as extensions, rather than custom metadata. (I realize there are some pre-existing references to custom metadata in the repo--I'm mostly thinking about the new content that we add.)

Add reference documentation

bde8fdb

dixonjoel requested a review from csjall as a code owner October 15, 2025 19:02

Copilot AI review requested due to automatic review settings October 15, 2025 19:02

Copilot AI reviewed Oct 15, 2025

View reviewed changes

dixonjoel requested review from ccifra and nick-beer October 15, 2025 19:06

Merge remote-tracking branch 'origin/main' into users/jdixon/add-refe…

4bb1e0a

…rence-documentation

csjall approved these changes Oct 16, 2025

View reviewed changes

hunter-ni reviewed Oct 17, 2025

View reviewed changes

		@@ -0,0 +1,389 @@
		# NI Metadata Store

		The NI Metadata Store support the digital thread weaving together measurement results with metadata that describes who, what, where, and how tests are performed. This creates a complete context around your test data, enabling traceability and analysis across your entire test ecosystem.

	The NI Metadata Store support the digital thread weaving together measurement results with metadata that describes who, what, where, and how tests are performed. This creates a complete context around your test data, enabling traceability and analysis across your entire test ecosystem.
	The NI Metadata Store supports the digital thread weaving together measurement results with metadata that describes who, what, where, and how tests are performed. This creates a complete context around your test data, enabling traceability and analysis across your entire test ecosystem.

	f"$filter=outcome eq 'OUTCOME_FAILED' and contains(hardware_item_ids, '{dmm_id}')"
	f"$filter=outcome eq 'OUTCOME_FAILED' and hardware_item_ids/any(id: id eq '{dmm_id}')"

Add reference documentation #46

Are you sure you want to change the base?

Add reference documentation #46

Conversation

dixonjoel commented Oct 15, 2025

What does this Pull Request accomplish?

Why should this Pull Request be merged?

What testing has been done?

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

dixonjoel commented Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hunter-ni Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hunter-ni Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dixonjoel commented Oct 15, 2025 •

edited

Loading

hunter-ni Oct 17, 2025 •

edited

Loading

hunter-ni Oct 17, 2025 •

edited

Loading