{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"redocly_category":"Products","product_name":"Integration Hub","type":"markdown"},"seo":{"title":"Ingesting JSON Event Properties JSON Remapping","description":"Treasure Data Product Documentation · Collect and Unify · Segment and Activate · Experiment and Analyze · Decisioning Automate with AI Scale and Trust.","siteUrl":"https://docs.treasuredata.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"ingesting-json-event-properties-json-remapping","__idx":0},"children":["Ingesting JSON Event Properties JSON Remapping"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JSON Ingest Remapping"]}," feature enables customers to extract deeply nested JSON fields and promote them to the top level during ingestion into the Real-Time pipeline."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This makes those fields directly accessible in Real-Time workflows — including T",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["riggers, Personalization, Reactor, and Plazma"]}," — without requiring upstream flattening, Lambda functions, or custom ETL."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"when-to-use","__idx":1},"children":["When to Use"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use JSON Ingest Remapping when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You have nested JSON events coming into the Real-Time ingestion pipeline."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You want to use inner fields (e.g. user.id, order.details.total) in segmentation, triggering, or personalization rules."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You want to avoid the cost and complexity of flattening data upstream or modifying source systems."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"how-it-works","__idx":2},"children":["How It Works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You define a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["mapping rule"]}," that specifies:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The source field path (within the nested JSON)"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The name of the new top-level field that will hold the extracted value"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These rules are configured via the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Real-Time API"]}," and are applied per database.table."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once applied, any incoming event that matches the table and contains the nested path will have the remapped field injected as a top-level property at ingest time."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"setup-steps","__idx":3},"children":["Setup Steps"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enable the Account (One-Time)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This feature is gated behind a flag. Please contact your Customer Success Manager or Treasure Support to have it enabled for your account."]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":2},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure Mapping via API"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the PUT /event_property_remappings endpoint:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Example Request:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X PUT 'https://realtime-api.treasuredata.com/event_property_remappings' \\\n--header 'Authorization: TD1 <your_apikey>' \\\n--header 'Content-Type: application/json' \\\n--data '\n{\n  \"event_property_remappings\": [\n    {\n      \"database\": \"demo\",\n      \"table\": \"customers\",\n      \"source_property_path\": \"order.details.total\",\n      \"target_property\": \"order_total\"\n    }\n  ]\n}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can also automate this via Digdag or workflows."]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":3},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ingest Your Events"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ingest events normally via the [Ingest API] or [Personalization API]. The remapped field will be automatically injected at the top level."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Example Input:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"order\": {\n    \"details\": {\n      \"total\": 149.99\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Result after remapping:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"order\": {\n    \"details\": {\n      \"total\": 149.99\n    }\n  },\n  \"order_total\": 149.99\n}\n","lang":"json"},"children":[]}]},"headings":[{"value":"Ingesting JSON Event Properties JSON Remapping","id":"ingesting-json-event-properties-json-remapping","depth":1},{"value":"When to Use","id":"when-to-use","depth":1},{"value":"How It Works","id":"how-it-works","depth":1},{"value":"Setup Steps","id":"setup-steps","depth":2}],"frontmatter":{"seo":{"title":"Ingesting JSON Event Properties JSON Remapping"}},"lastModified":"2026-06-01T09:09:59.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/customer-data-platform/integration-hub/streaming/ingesting-json-event-properties-json-remapping","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}