reading-data（读取数据）

Skill: TraceMem Reading Data (Data Products)

Purpose

This skill teaches how to safely and correctly read data using TraceMem Data Products. Direct database selection or API calls are prohibited; all data access must be mediated by TraceMem.

When to Use

• When you need to retrieve information (database rows, API results, resource state).
• When you need to search or query for specific records.

When NOT to Use

• Do not use for writing data (use decision_write / insert product).
• Do not try to use standard SQL libraries or HTTP clients for governed data.

Core Rules

• Data Products Only: You must access data via a named "Data Product".
• Operation Specificity: A Data Product usually supports only ONE operation. Use a "read" product (e.g., customers_read) for reading.
• Purpose is Mandatory: You must declare a purpose string for every read. This purpose must be in the product's allowed_purposes list.
• Least Privilege: Only request the data you strictly need.

Correct Usage Pattern

1. Identify the Product:

Use products_list to find the correct Data Product for your need (e.g., orders_read_v1). Check its schema and allowed_purposes.

1. Execute Read:

Call decision_read with: - decision_id: Your current open decision. - product: The name of the data product. - purpose: A valid purpose string (e.g., verification). - query: The key-value filter (e.g., {"user_id": "123"}).

1. Handle Results:

The response contains records (list) and summary.

*Example*:

   {
     "records": [{"id": 1, "status": "active"}],
     "summary": {"rows": 1}
   }

Common Mistakes

• Implicit Purpose: Failing to provide a purpose or guessing one not in the allowed list.
• Wrong Product: Trying to read from a product designed for insert.
• Unbounded Queries: Querying without filters (TraceMem may limit result sets by default).

Safety Notes

• Audit Trails: Your query parameters and the summary of what you read are recorded in the immutable trace.
• Sensitive Data: Avoid putting PII in the *query* parameters if possible, unless the Data Product is explicitly designed for PII lookups.
• Read-Before-Write: Always read the current state of an object before attempting to modify it, to ensure your decision is based on fresh data.