- Introduction
- Prerequisite
- Supported Relationship Types
- Relationship and Lineage Service operations
- Status Publish
- API Specifications
- Best practices
The relationship service enables you to find the relationship between pieces of data and perform queries based on them. The relationships are categorised as:
- Data relationships: Relationship between various entities in the domain data model. For example, a well log is related to a wellbore.
- Lineage relationships: Relationship between various transformed or modified data records. Lineage enables you to trace data forward (Derivatives) and backward (Ancestors) in time.
The record must be present in the data platform storage.
The following are the types of relationship that are supported by the Relationship and Lineage Service:
If a record has "toOne" and/or "toMany" relationship record IDs inside its "relationships" block, then it is considered an SLB style relationship.
The following is an example of this type of relationship:
Example of SLB Style relationship
"relationships": {
"wellbore": {
"id": "{datapartition}:trajectory:52456f368b1d41c3894fae7908a6dcef"
},
"relatedItems": {
"confidences": [
1,
1
],
"ids": [
"{datapartition}:field:56c3b39f3c684aa48b67b414b9ab0c95",
"{datapartition}:field:7b19370a07ac4a82bd1f191e574d603c"
],
"names": [
"SLB Field 1",
"SLB Field 2"
]
},
"logs": {
"ids": [
"{datapartition}:log:5fbba4e81dbc49128def1ab2a7b1bed3",
"{datapartition}:log:17e67d1fd5a348-21April21-not-created"
]
},
"parentEntity": {
"confidence": 1,
"id": "{datapartition}:wellbore:d56eb2aaff2741aaaa0916e812ad9478",
"name": "SLB Wellbore"
}
}
Relationship entities in OSDU are flagged as 'x-osdu-relationship' in the schema. The Relationship and Lineage Service identifies these 'x-osdu-relationship' entities, which have a group type of "master-data" or "work-product-component," or "Dataset," or "Work Product," or "Data Collections," and process them to establish relationship links.
The following is an example of an OSDU Schema Fragement with a relevant record:
OSDU Schema Fragement
{
"BasinID": {
"pattern": "^[\\w\\-\\.]+:master-data\\-\\-Basin:[\\w\\-\\.\\:\\%]+:[0-9]*$",
"description": "Reference to Basin.",
"x-osdu-relationship": [
{
"EntityType": "Basin",
"GroupType": "master-data"
}
],
"type": "string"
},
"DataSourceOrganisationID": {
"x-osdu-relationship": [
{
"EntityType": "Organisation",
"GroupType": "master-data"
}
],
"pattern": "^[\\w\\-\\.]+:master-data\\-\\-Organisation:[\\w\\-\\.\\:\\%]+:[0-9]*$",
"description": "The main source of the header information.",
"type": "string"
},
"InitialOperatorID": {
"x-osdu-relationship": [
{
"EntityType": "Organisation",
"GroupType": "master-data"
}
],
"pattern": "^[\\w\\-\\.]+:master-data\\-\\-Organisation:[\\w\\-\\.\\:\\%]+:[0-9]*$",
"description": "A initial operator organization ID; the organization ID may also be found in the FacilityOperatorOrganisationID of the FacilityOperator array providing the actual dates.",
"type": "string",
"title": "Initial Operator ID"
},
"CurrentOperatorID": {
"x-osdu-relationship": [
{
"EntityType": "Organisation",
"GroupType": "master-data"
}
],
"pattern": "^[\\w\\-\\.]+:master-data\\-\\-Organisation:[\\w\\-\\.\\:\\%]+:[0-9]*$",
"description": "The current operator organization ID; the organization ID may also be found in the FacilityOperatorOrganisationID of the FacilityOperator array providing the actual dates.",
"type": "string",
"title": "Current Operator ID"
},
"KickOffWellbore": {
"x-osdu-relationship": [
{
"EntityType": "Wellbore",
"GroupType": "master-data"
}
],
"pattern": "^[\\w\\-\\.]+:master-data\\-\\-Wellbore:[\\w\\-\\.\\:\\%]+:[0-9]*$",
"description": "This is a pointer to the parent wellbore. The wellbore that starts from top and has no parent.",
"type": "string"
},
"DefinitiveTrajectoryID": {
"x-osdu-relationship": [
{
"EntityType": "WellboreTrajectory",
"GroupType": "work-product-component"
}
],
"pattern": "^[\\w\\-\\.]+:work-product-component\\-\\-WellboreTrajectory:[\\w\\-\\.\\:\\%]+:[0-9]*$",
"description": "SRN of Wellbore Trajectory which is considered the authoritative or preferred version.",
"type": "string"
}
}
Sample Record Containing 'x-osdu-relationship' Entities
[
{
"data": {
"GeoContexts": [
{
"BasinID": "{datapartition}:master-data--Basin:e407fe6579924a9abbf6a38fc6dbdcd6:1632295934006112",
"GeoTypeID": "{datapartition}:reference-data--BasinType:ArcWrenchOceanContinent:"
}
],
"VersionCreationReason": "Example VersionCreationReason",
"FacilityID": "Example External Facility Identifier",
"FacilityTypeID": "{datapartition}:reference-data--FacilityType:Well:",
"InitialOperatorID": "{datapartition}:master-data--Organisation:29465ed80623438b8cfe8cada86f5365:1632296027337347",
"CurrentOperatorID": "{datapartition}:master-data--Organisation:8b5e22d06da841f9a896c42c4d972a6b:1632296072081115",
"DataSourceOrganisationID": "{datapartition}:master-data--Organisation:9a908fa505bd4990bb7c3cdff667220a",
"OperatingEnvironmentID": "{datapartition}:reference-data--OperatingEnvironment:Onshore:",
"FacilityName": "Example FacilityName",
"WellID": "{datapartition}:master-data--Well:9d93308ed80c4c55a23fcf3c83b8640e:1632296260655916",
"SequenceNumber": 2,
"VerticalMeasurements": [
{
"VerticalMeasurementID": "Example VerticalMeasurementID",
"EffectiveDateTime": "2020-02-13T09:13:15.55Z",
"VerticalMeasurement": 12345.6,
"TerminationDateTime": "2020-02-13T09:13:15.55Z",
"VerticalMeasurementTypeID": "{datapartition}:reference-data--VerticalMeasurementType:PBD:",
"VerticalMeasurementPathID": "{datapartition}:reference-data--VerticalMeasurementPath:MD:",
"VerticalMeasurementSourceID": "{datapartition}:reference-data--VerticalMeasurementSource:DRL:",
"WellboreTVDTrajectoryID": "{datapartition}:work-product-component--WellboreTVDTrajectory:f7c4dae12bbb4ed584d2b56a279bf2b7:1632296563088623",
"VerticalMeasurementUnitOfMeasureID": "{datapartition}:reference-data--UnitOfMeasure:m:",
"VerticalCRSID": "{datapartition}:reference-data--CoordinateReferenceSystem:BoundCRS::OSDU::23031018:",
"VerticalReferenceID": "Example VerticalReferenceID",
"VerticalMeasurementDescription": "Example VerticalMeasurementDescription"
}
],
"KickOffWellbore": "{datapartition}:master-data--Wellbore:9eade4adcf9842a689f15b1cf217c052:1632296728249406",
"DefinitiveTrajectoryID": "{datapartition}:work-product-component--WellboreDefinitiveTrajectory:a2e8255618b144598ea72210f129755f:1632296617400827"
},
"meta": [],
"kind": "osdu:wks:master-data--Wellbore:1.0.0",
"acl": {
"viewers": [
"{acl_viewer}"
],
"owners": [
"{acl_owner}"
]
},
"legal": {
"legaltags": [
"{legal-tag}"
],
"otherRelevantDataCountries": [
"US"
],
"status": "compliant"
},
"ancestry": {
"parents": [
"{datapartition}:master-data--Well:72de2620f36e4e6d95874f4eab0d950b:1633593222572292"
]
}
}
]
Data records can have relationship entities inside an "ExtensionProperties" block, which is called a non-schema driven or a generic relationship. Relationship and Lineage Service identifies such relationship entities from a data record and processes it to establish relationship links.
The following is an example of this type of data record:
Sample Record containing Relationship Entities inside ExtensionProperties
[
{
"data": {
"VersionCreationReason": "Example VersionCreationReason",
"FacilityID": "Example External Facility Identifier",
"FacilityTypeID": "{datapartition}:reference-data--FacilityType:Well:",
"InitialOperatorID": "{datapartition}:master-data--Organisation:29465ed80623438b8cfe8cada86f5365:1632296027337347",
"CurrentOperatorID": "{datapartition}:master-data--Organisation:8b5e22d06da841f9a896c42c4d972a6b:1632296072081115",
"DataSourceOrganisationID": "{datapartition}:master-data--Organisation:9a908fa505bd4990bb7c3cdff667220a",
"OperatingEnvironmentID": "{datapartition}:reference-data--OperatingEnvironment:Onshore:",
"FacilityName": "Example FacilityName",
"SequenceNumber": 2,
"VerticalMeasurements": [
{
"VerticalMeasurementID": "Example VerticalMeasurementID",
"EffectiveDateTime": "2020-02-13T09:13:15.55Z",
"VerticalMeasurement": 12345.6,
"TerminationDateTime": "2020-02-13T09:13:15.55Z",
"VerticalMeasurementTypeID": "{datapartition}:reference-data--VerticalMeasurementType:PBD:",
"VerticalMeasurementPathID": "{datapartition}:reference-data--VerticalMeasurementPath:MD:",
"VerticalMeasurementSourceID": "{datapartition}:reference-data--VerticalMeasurementSource:DRL:",
"WellboreTVDTrajectoryID": "{datapartition}:work-product-component--WellboreTVDTrajectory:f7c4dae12bbb4ed584d2b56a279bf2b7:1632296563088623",
"VerticalMeasurementUnitOfMeasureID": "{datapartition}:reference-data--UnitOfMeasure:m:",
"VerticalCRSID": "{datapartition}:reference-data--CoordinateReferenceSystem:BoundCRS::OSDU::23031018:",
"VerticalReferenceID": "Example VerticalReferenceID",
"VerticalMeasurementDescription": "Example VerticalMeasurementDescription"
}
],
"DefinitiveTrajectoryID": "{datapartition}:work-product-component--WellboreDefinitiveTrajectory:a2e8255618b144598ea72210f129755f:1632296617400827",
"ExtensionProperties": {
"Relationships": [
{
"TargetID": "{datapartition}:field:4c73ebdb90d84b5096ef6fe54b37d7cd",
"RelationshipName": "Field",
},
{
"TargetID": "{datapartition}:document:d783ba8b8985411f8fb57ad1bad18c06",
"RelationshipName": "Document"
}
]
}
},
"meta": [],
"kind": "osdu:wks:master-data--Well:1.0.0",
"acl": {
"viewers": [
"{acl_viewer}"
],
"owners": [
"{acl_owner}"
]
},
"legal": {
"legaltags": [
"{legal-tag}"
],
"otherRelevantDataCountries": [
"US"
],
"status": "compliant"
},
"ancestry": {
"parents": [
"{datapartition}:master-data--Well:72de2620f36e4e6d95874f4eab0d950b:1633593222572292"
]
}
}
]The Relationship and Lineage Service includes the following endpoints:
- GET associations/{id} - Lists the related data to the latest version of queried record and the shortest relationship path to the related data.
- GET {id}/associations/summary - Lists a summary(count) of related data to the latest version of the queried record.
- POST associations/summary:batch - Lists summary(count) of related data for multiple records(with latest version).
- GET records/{id}/ancestors - Lists the records from which the queried record is derived.
- GET records/{id}/derivatives - Lists the records which are derived from the queried record.
- GET records/{id}/lineageAssertions - Lists the lineage asserted entities for the queried record.
You can get the associated entities of the queried record using the GET /associations endpoint. The following parameters are used to find and filter the related data:
Endpoint: GET https://{DNS_HOST}/api/relationship-service/v1/records/{recordID}/associations?level={level}&type={type}
| Attribute | Use | Example | Datatype | Required (Yes/No) |
|---|---|---|---|---|
| Record id | This is the unique ID of the record for which the relationship is searched. This is a mandatory input. | {datapartition}:master-data--Wellbore:09c55df19a16426c959c8ecfc8648170 | String | Yes |
| type | This optional parameter is used to filter the related data based on it's entity type. | master-data--Basin, master-data--Field, work-product-component--WellboreTrajectory | String | No If not given, then it provides all types of entities. |
| level | This is an optional parameter that specifies the search distance starting from the record for which related data is fetched. The distance is measured in terms of 'levels' from the starting record. | In a relationship where master-data--Basin-> master-data--Field-> master-data--Wellbore-> work-product-component--WellboreTrajectory. The master-data--Wellbore is at level 2 from the master-data--Basin, and the work-product-component--WellboreTrajectory is at level 3 from master-data--Basin. Currently, the maximum level supported by default is 5. So, the value of this parameter can range from 1 to 5. | Number | No If not given, it provides entities associated at first level. |
| lineage-level | This parameter gets the related entities which are not linked to the queried record but linked to the record from which the queried record is derived. | If WKE Wellbore 'A' is derived from WKS Wellbore 'B' and this WKS Wellbore 'B' has some related entities like logs 'L1','L2' which are not linked to the WKE Wellbore 'A' then, using lineage-level=1, you can get logs 'L1', 'L2' which are linked to the WKS Wellbore. Currently, the maximum level supported is 5 and default value is 0(zero). | Number | No If not given or if the given value is 0, it provides only those entities which are linked to the queried record and not to the lineage records. |
Sample Response of the Association API
{
"entity": {
"id": "{datapartition}:master-data--Wellbore:09c55df19a16426c959c8ecfc8648170",
"type": "master-data--Wellbore"
},
"associates": [
{
"entity": {
"id": "{datapartition}:work-product-component--Document:fdf2dd2c52044ec0b836083110735975",
"type": "work-product-component--Document"
},
"shortestPaths": [
{
"paths": [
{
"associationType": "RELATIONSHIP",
"id": "{datapartition}:work-product-component--Document:fdf2dd2c52044ec0b836083110735975"
}
]
}
],
"totalPaths": 1
},
{
"entity": {
"id": "{datapartition}:master-data--Well:8896d0d348ca45ed8a8a7b049a322eb3",
"type": "master-data--Well"
},
"shortestPaths": [
{
"paths": [
{
"associationType": "RELATIONSHIP",
"id": "{datapartition}:master-data--Well:8896d0d348ca45ed8a8a7b049a322eb3"
}
]
}
],
"totalPaths": 2
},
{
"entity": {
"id": "{datapartition}:master-data--Organisation:ddaa5d604afc4bc187402bf2dcf96fd7",
"type": "master-data--Organisation"
},
"shortestPaths": [
{
"paths": [
{
"associationType": "RELATIONSHIP",
"id": "{datapartition}:master-data--Organisation:ddaa5d604afc4bc187402bf2dcf96fd7"
}
]
}
],
"totalPaths": 1
},
{
"entity": {
"id": "{datapartition}:master-data--Organisation:1e0a35aff2334ca885703b038130a32d",
"type": "master-data--Organisation"
},
"shortestPaths": [
{
"paths": [
{
"associationType": "RELATIONSHIP",
"id": "{datapartition}:master-data--Organisation:1e0a35aff2334ca885703b038130a32d"
}
]
}
],
"totalPaths": 1
},
{
"entity": {
"id": "{datapartition}:master-data--Organisation:1f31b081390a4efaa8a71619dfd90065",
"type": "master-data--Organisation"
},
"shortestPaths": [
{
"paths": [
{
"associationType": "RELATIONSHIP",
"id": "{datapartition}:master-data--Organisation:1f31b081390a4efaa8a71619dfd90065"
}
]
}
],
"totalPaths": 1
},
{
"entity": {
"id": "{datapartition}:master-data--Wellbore:86ce3adf595a480c9b5fbef5b28d592b",
"type": "master-data--Wellbore"
},
"shortestPaths": [
{
"paths": [
{
"associationType": "RELATIONSHIP",
"id": "{datapartition}:master-data--Wellbore:86ce3adf595a480c9b5fbef5b28d592b"
}
]
}
],
"totalPaths": 4
},
{
"entity": {
"id": "{datapartition}:work-product-component--WellboreTrajectory:c1a98c16db7b44aca312a73cd9b43184",
"type": "work-product-component--WellboreTrajectory"
},
"shortestPaths": [
{
"paths": [
{
"associationType": "RELATIONSHIP",
"id": "{datapartition}:work-product-component--WellboreTrajectory:c1a98c16db7b44aca312a73cd9b43184"
}
]
}
],
"totalPaths": 4
},
{
"entity": {
"id": "{datapartition}:master-data--Organisation:dcb8e00040dc40009744775a827d6d5c",
"type": "master-data--organisation"
},
"shortestPaths": [
{
"paths": [
{
"associationType": "RELATIONSHIP",
"id": "{datapartition}:master-data--Organisation:dcb8e00040dc40009744775a827d6d5c"
}
]
}
],
"totalPaths": 1
},
{
"entity": {
"id": "{datapartition}:master-data--Organisation:88250b359c5f4621b384e71a3814c617",
"type": "master-data--organisation"
},
"shortestPaths": [
{
"paths": [
{
"associationType": "RELATIONSHIP",
"id": "{datapartition}:master-data--Organisation:88250b359c5f4621b384e71a3814c617"
}
]
}
],
"totalPaths": 1
},
{
"entity": {
"id": "{datapartition}:master-data--Basin:20f17bc1170947f0974835c00d1b43a4",
"type": "master-data--basin"
},
"shortestPaths": [
{
"paths": [
{
"associationType": "RELATIONSHIP",
"id": "{datapartition}:master-data--Basin:20f17bc1170947f0974835c00d1b43a4"
}
]
}
],
"totalPaths": 2
},
{
"entity": {
"id": "{datapartition}:work-product-component--WellboreTrajectory:568c531f88144da4a1963b5a700e401a",
"type": "work-product-component--wellboretrajectory"
},
"shortestPaths": [
{
"paths": [
{
"associationType": "RELATIONSHIP",
"id": "{datapartition}:master-data--Well:8896d0d348ca45ed8a8a7b049a322eb3"
},
{
"associationType": "RELATIONSHIP",
"id": "{datapartition}:work-product-component--WellboreTrajectory:568c531f88144da4a1963b5a700e401a"
}
]
}
],
"totalPaths": 4
},
{
"entity": {
"id": "{datapartition}:master-data--GeoPoliticalEntity:18f175751c41476d91f780091548aba4",
"type": "master-data--geopoliticalentity"
},
"shortestPaths": [
{
"paths": [
{
"associationType": "ANCESTRY",
"id": "{datapartition}:master-data--Well:be6abb540a484947b3de8d468500c283"
},
{
"associationType": "RELATIONSHIP",
"id": "{datapartition}:master-data--GeoPoliticalEntity:18f175751c41476d91f780091548aba4"
}
]
}
],
"totalPaths": 2
},
{
"entity": {
"id": "{datapartition}:marker:eb24e164f7e84f72ae2f3c3d6f213ff3",
"type": "marker"
},
"shortestPaths": [
{
"paths": [
{
"associationType": "ANCESTRY",
"id": "{datapartition}:master-data--Well:be6abb540a484947b3de8d468500c283"
},
{
"associationType": "ANCESTRY",
"id": "{datapartition}:well:6b38440c618b44c4b395cebe64a1fc6f"
},
{
"associationType": "RELATIONSHIP",
"id": "{datapartition}:marker:eb24e164f7e84f72ae2f3c3d6f213ff3"
}
]
}
],
"totalPaths": 1
}
]
}
Here, "shortestPaths" indicates how a queried record is linked with a related entity.
As mentioned in the above example, a queried record ({datapartition}:master-data--Wellbore:09c55df19a16426c959c8ecfc8648170) is directly linked to "master-data--Organisation" ({datapartition}:master-data--Organisation:ddaa5d604afc4bc187402bf2dcf96fd7), while the same queried record is linked to "work-product-component--WellboreTrajectory" ({datapartition}:work-product-component--WellboreTrajectory:568c531f88144da4a1963b5a700e401a) via the "master-data--Well" record ({datapartition}:master-data--Well:8896d0d348ca45ed8a8a7b049a322eb3) which is indirect linking.
Also, the above sample response contains a lineage-relationship record ({datapartition}:marker:eb24e164f7e84f72ae2f3c3d6f213ff3). Here, the queried master-data--wellbore is derived from {datapartition}:master-data--Well:be6abb540a484947b3de8d468500c283 and this master-data--Well is derived from {datapartition}:well:6b38440c618b44c4b395cebe64a1fc6f which is linked to the marker. Therefore, the marker is linked to the queried master-data--Wellbore at lineage-level = 2.
You can get the details (such as "Name", "FacilityID", "VerticalMeasurements" etc) of the associated entities of the queried record using the POST /associations/details endpoint. The following parameters are used to find and filter the related data:
Endpoint: POST https://{DNS_HOST}/api/relationship-service/v1/records/associations/details
Sample Request
{
"recordId": "{datapartition}:master-data--GeoPoliticalEntity:2b9da88fef1149c6a896b40ab13a6dea",
"level": 1,
"pageNumber":1,
"returnedFields": [
"id",
"kind",
"tags",
"data.Name",
"data.NameAliases",
"data.AgreementName",
"data.BasinName",
"data.FieldName",
"data.GeoPoliticalEntityName",
"data.OrganisationName",
"data.PlayName",
"data.ProspectName",
"data.FacilityName",
"data.AttributionAuthority",
"data.GeoPoliticalEntityTypeID",
"data.WellLogTypeID",
"data.Curves"
],
"types": [
"master-data--Wellbore","master-data--Well"
]
}
| Attribute | Use | Example | Datatype | Required (Yes/No) |
|---|---|---|---|---|
| Record id | This is the unique ID of the record for which the relationship is searched. This is a mandatory input. | {datapartition}:master-data--Wellbore:09c55df19a16426c959c8ecfc8648170 | String | Yes |
| returnedFields | Here, you can pass the OSDU Schema Supported attributes to get them in response for associated entities. | As seen in above example | Array of String | No. If not given, API gives all the attributes of respective associated entities in response |
| types | This optional parameter is used to filter the related data based on it's entity type. | master-data--Basin, master-data--Field, work-product-component--WellboreTrajectory | Array of String | No If not given, then it provides all types of entities. |
| level | This is an optional parameter that specifies the search distance starting from the record for which related data is fetched. The distance is measured in terms of 'levels' from the starting record. | In a relationship where master-data--Basin-> master-data--Field-> master-data--Wellbore-> work-product-component--WellboreTrajectory. The master-data--Wellbore is at level 2 from the master-data--Basin, and the work-product-component--WellboreTrajectory is at level 3 from master-data--Basin. Currently, the maximum level supported by default is 5. So, the value of this parameter can range from 1 to 5. | Number | No If not given, it provides entities associated at first level. |
| pageNumber | This parameters allows user to iterate through the number of associated entities page by page. Here, one page can have maximum of 100 associated entities. Also, please note that, this API gives maximum of 1,000 associated entities in total. Hence, max number of page size can be 10. | "pageNumber": 1, "pageNumber": 2, "pageNumber": 3 | Number | No If not given, then it provides the associated entities present at first page. |
Sample Response
{
"entity": {
"id": "{datapartition}:master-data--GeoPoliticalEntity:2b9da88fef1149c6a896b40ab13a6dea",
"type": "master-data--GeoPoliticalEntity"
},
"associates": [
{
"data": {
"FacilityName": "SLB-Facility-A"
},
"kind": "osdu:wks:master-data--Wellbore:1.1.0",
"id": "{datapartition}:master-data--Wellbore:5ba113340e2a434f8f29aac670404256",
"tags": {
"normalizedKind": "osdu:wks:master-data--Wellbore:1"
}
},
{
"data": {
"FacilityName": "SLB-Facility-B"
},
"kind": "osdu:wks:master-data--Wellbore:1.1.0",
"id": "{datapartition}:master-data--Wellbore:f603583f8304464f8243cf045f9869fa",
"tags": {
"normalizedKind": "osdu:wks:master-data--Wellbore:1"
}
},
{
"data": {
"FacilityName": "SLB-Facility-A"
},
"kind": "osdu:wks:master-data--Well:1.0.0",
"id": "{datapartition}:master-data--Well:268e168e2b7449e09973d45f352e0487",
"tags": {
"NameOfKey": "String value"
}
},
{
"data": {
"FacilityName": "SLB-Facility-B"
},
"kind": "osdu:wks:master-data--Well:1.0.0",
"id": "{datapartition}:master-data--Well:b9d3d735dc4b47f099c9389fcc28e4ea",
"tags": {
"NameOfKey": "String value"
}
}
],
"totalCount": 4
}
The summary API lists a summary of related entities along with the count of each entity. You can get the associated summary using the GET /associations/summary endpoint. The following parameters are used to find and filter the related data:
Endpoint: GET https://{DNS_HOST}/api/relationship-service/v1/records/{recordID}/associations/summary?level={level}&type={type}
| Attribute | Use | Example | Datatype | Required (Yes/No) |
|---|---|---|---|---|
| Record id | This is the unique ID of the record for which the relationship is searched. This is a mandatory input. | {datapartition}:master-data--Wellbore:09c55df19a16426c959c8ecfc8648170 | String | Yes |
| type | This optional parameter is used to filter the related data based on their entity type. | master-data--Basin, master-data--Field, work-product-component--WellboreTrajectory | String | No If not given then it provides all types of entities. |
| level | This is an optional parameter that specifies the search distance starting from the record for which related data is fetched. The distance is measured in terms of 'levels' from the starting record. | In a relationship where master-data--Basin-> master-data--Field-> master-data--Wellbore-> work-product-component--WellboreTrajectory. The master-data--Wellbore is at level 2 from the master-data--Basin, and the work-product-component--WellboreTrajectory is at level 3 from master-data--Basin. Currently, the maximum level supported by default is 5. So, the value of this parameter can range from 1 to 5. | Number | No If not given, it provides entities associated at first level. |
Here, as per the current implementation, the summary endpoint does not allow to get lineage-level entities count.
Sample Response of the Summary API
[
{
"type": "master-data--Basin",
"count": 1
},
{
"type": "master-data--Well",
"count": 2
},
{
"type": "master-data--Organisation",
"count": 3
},
{
"type": "work-product-component--WellboreTrajectory",
"count": 1
}
]
The POST /associations/summary:batch endpoint allows you to get a summary of related entities of multiple records in single request. You can get the associated summary of multiple records by providing the record IDs in the request payload as shown in the following sample request. A maximum of 100 record IDs are supported in a single request.
Endpoint: POST https://{DNS_HOST}/api/relationship-service/v1/records/associations/v2/summary:batch?level={level}&type={type}
Sample Request
{
"records": [
"{datapartition}:master-data--Wellbore:0b58b42f43ea42aebc7f4c9d5a4d2c97",
"{datapartition}:master-data--Wellbore:295e80f9e22f4604b84cb139829efacf",
"{datapartition}:master-data--Wellbore:63a2761ac4e542cead786c0e43f9215a",
"{datapartition}:master-data--Wellbore:0105ba4f5fdd428eb3fcd4827d52e552",
"{datapartition}:wke:master-data--Wellbore-375b4e81-1fdf-4d18-a3d4-34efb44be852",
"{datapartition}:wks:master-data--Basin-245b4w81-1erf-5h24-b4e5-45fgc33cf963"
]
}
The following parameters are used to find and filter the related data:
| Attribute | Use | Example | Datatype | Required (Yes/No) |
|---|---|---|---|---|
| type | This optional parameter is used to filter the related data based on their entity type. | master-data--Basin, master-data--Field, work-product-component--WellboreTrajectory | String | No If not given, it provides all types of entities. |
| level | This is an optional parameter that specifies the search distance starting from the record for which related data is fetched. The distance is measured in terms of 'levels' from the starting record. | In a relationship where master-data--Well-> master-data--Wellbore-> work-product-component--WellboreTrajectory-> CompanyID, the work-product-component--WellboreTrajectory is at level 2 from the master-data--Well, and the CompanyID is at level 3 from master-data--Well. Currently, the maximum level supported by default is 5. So, the value of this parameter can range from 1 to 5. | Number | No If not given, it provides the entities associated at up to the maximum level of 5. |
Here, as per the current implementation, this endpoint is not allowed to get the lineage-level entities count.
Response of the summary:batch API
{
"records": [
{
"recordId": "{datapartition}:master-data--Wellbore:0b58b42f43ea42aebc7f4c9d5a4d2c97",
"summary": [
{
"type": "master-data--Well",
"count": 1
},
{
"type": "master-data--Wellbore",
"count": 1
}
]
},
{
"recordId": "{datapartition}:master-data--Wellbore:63a2761ac4e542cead786c0e43f9215a",
"summary": [
{
"type": "wellborecompletion",
"count": 1
},
{
"type": "master-data--Basin",
"count": 1
},
{
"type": "work-product-component--WellboreTrajectory",
"count": 1
},
{
"type": "master-data--Well",
"count": 1
},
{
"type": "master-data--Wellbore",
"count": 1
},
{
"type": "master-data--Organisation",
"count": 5
}
]
},
{
"recordId": "{datapartition}:master-data--Wellbore:0105ba4f5fdd428eb3fcd4827d52e552",
"summary": [
{
"type": "master-data--Well",
"count": 1
},
{
"type": "master-data--Wellbore",
"count": 2
}
]
},
{
"recordId": "{datapartition}:master-data--Wellbore:295e80f9e22f4604b84cb139829efacf",
"summary": [
{
"type": "master-data--Well",
"count": 1
},
{
"type": "master-data--Wellbore",
"count": 2
}
]
},
{
"recordId": "{datapartition}:master-data--Wellbore:0b58b42f43ea42aebc7f4c9d5a4d2c97",
"summary": [
{
"type": "wellborecompletion",
"count": 1
},
{
"type": "master-data--Basin",
"count": 1
},
{
"type": "work-product-component--WellboreTrajectory",
"count": 1
},
{
"type": "master-data--Well",
"count": 1
},
{
"type": "master-data--Wellbore",
"count": 1
},
{
"type": "master-data--Organisation",
"count": 5
}
]
}
],
"notFound": [
"{datapartition}:wks:master-data--Basin-245b4w81-1erf-5h24-b4e5-45fgc33cf963"
]
}
Here, as mentioned in the above example, the response contains the associated entities count for every record mentioned while sending the request. If you do not have access to a record or if the record does not exist in the data platform, the response “notFound” is returned.
The ancestor API enables you to understand from which record the queried record is derived. You can get the ancestors of any record using the GET /ancestors endpoint.
The input parameter for this API is the data record ID; for example: {datapartition}:master-data--Wellbore:c331b6057b6944de87dac803de6c96f9.
Endpoint: GET https://{DNS_HOST}/api/relationship-service/v1/records/{recordID}/ancestors
Response of the Ancestor API
{
"record": {
"id": "{datapartition}:master-data--Wellbore:c331b6057b6944de87dac803de6c96f9",
"type": "master-data--Wellbore"
},
"lineage": [
{
"record": {
"id": "{datapartition}:master-data--Well:be6abb540a484947b3de8d468500c283",
"type": "master-data--Well"
},
"lineage": [
{
"record": {
"id": "{datapartition}:well:6b38440c618b44c4b395cebe64a1fc6f",
"type": "well"
},
"lineage": []
}
]
},
{
"record": {
"id": "{datapartition}:master-data--Well:fe92bc00c1c144a2a7f226bbd22ea57d",
"type": "master-data--Well"
},
"lineage": []
}
]
}
The derivatives API enables you to understand how many records are created from a particular record. You can get the derivatives of any record using the GET /derivatives endpoint.
The input parameter for this API is the data record ID; for example: {datapartition}:well:6b38440c618b44c4b395cebe64a1fc6f.
Endpoint: GET https://{DNS_HOST}/api/relationship-service/v1/records/{recordID}/derivatives
Response of the Derivatives API
{
"record": {
"id": "{datapartition}:well:6b38440c618b44c4b395cebe64a1fc6f",
"type": "well"
},
"lineage": [
{
"record": {
"id": "{datapartition}:master-data--Well:be6abb540a484947b3de8d468500c283",
"type": "master-data--Well"
},
"lineage": [
{
"record": {
"id": "{datapartition}:wke:master-data--Wellbore-3b73d5a9-3d8f-4cb2-bd03-a146aa8edbea",
"type": "master-data--Wellbore"
},
"lineage": []
}
]
}
]
}
The lineage assertions API enables you to understand how many Lineage asserted entities are present for a queried WPC record. You can get the lineage assertions of any record using the GET /lineageAssertions endpoint.
The input parameter for this API is the data record ID; for example: ,{datapartition}:work-product-component--WellboreTrajectory:4c47e4f0e0f1413ca25ab2ba7f52656d.
Endpoint: GET https://{DNS_HOST}/api/relationship-service/v1/records/{recordID}/lineageAssertions
The API additionally shows the type of Lineage Relationship. E.g. :- Direct, Indirect and Reference. More details about these Lineage Relationship Type can be found in following table:
| LineageRelationshipType | Name | Description |
|---|---|---|
| Direct | Direct | A resource which was used to derive work product component through processes and transformations. Generally, data type is same for both resource and derived WPC |
| Indirect | Indirect | A resource which was used during derivation of work product component to control the process but is not directly transformed. Generally, data type is different for both resource and derived WPC |
| Reference | Reference | A resource which captures the information about the process to create the WPC, but is not directly used in the process |
The following parameter is used to find the lineage assertions for a certain record:
| Attribute | Use | Example | Datatype | Required (Yes/No) |
|---|---|---|---|---|
| Record id | This is the unique ID of the record for which the lineage assertions needs to be searched. This is a mandatory input. | {datapartition}:work-product-component--WellboreTrajectory:4c47e4f0e0f1413ca25ab2ba7f52656d | String | Yes |
Followng is the example of a sample record containing Lineage Assertion entities:
Sample Work Product Component Trajectory Record
[
{
"kind": "osdu:wks:work-product-component--WellboreTrajectory:1.1.0",
"acl": {
"viewers": [
"<acl-viewers>"
],
"owners": [
"<acl-owners>"
]
},
"legal": {
"legaltags": [
"<legal-tag>"
],
"otherRelevantDataCountries": [
"US"
],
"status": "compliant"
},
"tags": {
"NameOfKey": "String value"
},
"ancestry": {
"parents": [
"{datapartition}:trajectory:571c462c3bfa451b8d54cb34571152a3:1680171290704452"
]
},
"data": {
"IsExtendedLoad": true,
"IsDiscoverable": true,
"CreationDateTime": "2020-02-13T09:13:15.55Z",
"LineageAssertions": [
{
"ID": "{datapartition}:work-product-component--WellboreTrajectory:a1a514524e8041caa52e496c51f7c949:",
"LineageRelationshipType": "{datapartition}:reference-data--LineageRelationshipType:Direct:"
},
{
"ID": "{datapartition}:master-data--Wellbore:f6dec0a55ebc4561a5c555aca9945b7d:",
"LineageRelationshipType": "{datapartition}:reference-data--LineageRelationshipType:Reference:"
},
{
"ID": "{datapartition}:work-product-component--WellLog:1a7a210fc4b4494988294f64486016bd:",
"LineageRelationshipType": "{datapartition}:reference-data--LineageRelationshipType:Indirect:"
}
],
"TopDepthMeasuredDepth": 100.6,
"ActiveIndicator": true,
"SurveyType": "Example Directional Survey Type",
"AcquisitionDate": "2020-02-13T09:13:15.55Z",
"GeographicCRSID": "{datapartition}:reference-data--CoordinateReferenceSystem:Geographic2D:EPSG::4326:",
"SurveyToolTypeID": "{datapartition}:reference-data--SurveyToolType:MWD%2BSRGM_A001Mc:",
"SurveyVersion": "Example Survey Version",
"ExtrapolatedMeasuredDepth": 12345.6,
"BaseDepthMeasuredDepth": 12345.6,
"TieMeasuredDepth": 12345.6
}
}
]
Response of the Lineage assertions API
{
"record": {
"id": "{datapartition}:work-product-component--WellboreTrajectory:4c47e4f0e0f1413ca25ab2ba7f52656d",
"type": "work-product-component--WellboreTrajectory"
},
"lineage": [
{
"record": {
"id": "{datapartition}:work-product-component--WellboreTrajectory:a1a514524e8041caa52e496c51f7c949",
"type": "work-product-component--WellboreTrajectory",
"lineageRelationshipType": "Direct"
},
"lineage": [
{
"record": {
"id": "{datapartition}:log:442cc4a3b95d41dfa4872bf25901a02a",
"type": "log",
"lineageRelationshipType": "Direct"
},
"lineage": []
}
]
},
{
"record": {
"id": "{datapartition}:master-data--Wellbore:f6dec0a55ebc4561a5c555aca9945b7d",
"type": "master-data--Wellbore",
"lineageRelationshipType": "Reference"
},
"lineage": []
},
{
"record": {
"id": "{datapartition}:work-product-component--WellLog:1a7a210fc4b4494988294f64486016bd",
"type": "work-product-component--WellLog",
"lineageRelationshipType": "Indirect"
},
"lineage": []
}
]
}
The Relationship and Lineage service publishes the status of the processing of data and lineage relationships for every data record to statuschangetopic. You can track this staus using the Data Workspace - Data Flow Status Processor Service - POST /status/query API here.
For more details on this API, please refer to this Status Processor.
The following table shows the status details which the Relationship and Lineage service publishes when the processing of data and lineage relationships starts and completes:
| correlation-id | recordId | stage | status | message | errorCode | timestamp | additionalProperties |
|---|---|---|---|---|---|---|---|
| 123xxx456 | {datapartition}:master-data--Wellbore:09c55df19a16426c959c8ecfc8648170 | RELATIONSHIP_SYNC | SUCCESS | Processing of associated relationship and lineage entities is completed | 0 | 1639724121468 | { "noOfAssociatedRelationshipEntities": <number_of_associated_relationship_entities>, "noOfAncestorEntities": <number_of_associated_ancestor_entities>, "noOfLineageAssertionEntities": <number_of_Lineage_Assertion_entities> } |
The following is a sample query to track the status using the Data Workspace - Data Flow Status Processor Service - POST /status/query API:
Sample query to track the status
{
"statusQuery": {
"correlationId": "efe0d2f4-1d36-404f-94e5-22db867c6eb4",
"stage": ["RELATIONSHIP_SYNC"]
}
}
Sample Response
{
"results": [
{
"correlationId": "efe0d2f4-1d36-404f-94e5-22db867c6eb4",
"recordId": "{datapartition}:master-data--Wellbore:09c55df19a16426c959c8ecfc8648170",
"stage": "RELATIONSHIP_SYNC",
"status": "SUCCESS",
"message": "Processing of associated relationship and lineage entities has completed.",
"errorCode": 0,
"additionalProperties": {
"noOfAssociatedRelationshipEntities": 11.0,
"noOfLineageAssertionEntities": 4.0,
"noOfAncestorEntities": 3.0
},
"userEmail": "<user-email>",
"timestamp": 1642072935205
}
],
"count": 1,
"totalCount": 1,
"limit": 100
}
You can access the Relationship and Lineage Service - Get the associated entities, Get the summary of associated entities, Get the details of the associated entities, Get the summary of associated entities for multiple records, Get the ancestors of any record, Get the derivatives of any record and Get the lineage assertions of a record APIs here.
The record ID is a unique record identifier in the Data Platform. The record IDs can be system or user generated (provided in request). It must be composed of 3 components separated by colons, in which the first component must be the slb-partition-id. The expression must match a character (a-zA-Z_0-9) or the symbols "-", "." that occurs one or more times that is defined by the [\w-.]+ expressions group that are followed by the ":" symbol. As a best practice, compose the record ID as {data-partition-id}:{entity-type}:{unique-identifier} that meets the string validation of ^[\w-.]+:[\w-.]+:[\w-.:%]+$ pattern defined by OSDU Data Definition.
Record ID Example: {datapartition}:work-product-component--WellLog:a6d6-63fc9a0bbac1
Following is the Sample example of Work Product Component WellboreTrajectory Record containing valid Related Record IDs
[
{
"kind": "osdu:wks:work-product-component--WellboreTrajectory:1.1.0",
"acl": {
"viewers": [
"<acl-viewers>"
],
"owners": [
"<acl-owners>"
]
},
"legal": {
"legaltags": [
"<legal-tag>"
],
"otherRelevantDataCountries": [
"US"
],
"status": "compliant"
},
"tags": {
"NameOfKey": "String value"
},
"ancestry": {
"parents": [
"{datapartition}:trajectory:571c462c3bfa451b8d54cb34571152a3:1680171290704452"
]
},
"data": {
"WellboreID": "{datapartition}:master-data--Wellbore:c1c514524e8051caa72e496c51f7c748:",
"LineageAssertions": [
{
"ID": "{datapartition}:work-product-component--WellboreTrajectory:a1a514524e8041caa52e496c51f7c949:",
"LineageRelationshipType": "{datapartition}:reference-data--LineageRelationshipType:Direct:"
}
],
"GeoContexts": [
{
"GeoPoliticalEntityID": "{datapartition}:master-data--GeoPoliticalEntity:b1b514524e8041caa62fg496c51f7c808:"
}
]
}
}
]For an attribute, it is recommended to have the record ID format match the pattern specified as per the schema of the kind
Example :-
kind = osdu:wks:master-data--Wellbore:1.0.0
Pattern for attribute DataSourceOrganisationID = "^[\w-.]+:master-data--Organisation:[\w-.:%]+:[0-9]*$"
Sample Record ID for attribute DataSourceOrganisationID = "{datapartition}:master-data--Organisation:c1c614524e8041caa62fg496c51f7d909:"
Sample Schema Fragment of kind osdu:wks:master-data--Wellbore:1.0.0 for attribute DataSourceOrganisationID
[
{
"DataSourceOrganisationID": {
"x-osdu-relationship": [
{
"EntityType": "Organisation",
"GroupType": "master-data"
}
],
"pattern": "^[\w\-\.]+:master-data\-\-Organisation:[\w\-\.\:\%]+:[0-9]*$",
"description": "The main source of the header information.",
"type": "string"
}
}
]Related record Ids whose syntax is not as per OSDU data definition will be considered as invalid record Ids. Only those related record Ids which are following OSDU standard will be linked with the record under processing. Details of the Record which is getting processed is sent to Data Workspace - Data Flow Status Processor Service with status as "SUCCESS" along with reason for failure message as "RecordId is not in valid format" referring to which user can take required action.
Sample Work Product Component SeismicTraceData Record having invalid Related Record Ids
[
{
"kind": "osdu:wks:work-product-component--SeismicTraceData:1.0.0",
"acl": {
"viewers": [
"data.default.viewers@{datapartition}.enterprisedata.cloud.slb-ds.com"
],
"owners": [
"data.default.owners@{datapartition}.enterprisedata.cloud.slb-ds.com"
]
},
"legal": {
"legaltags": [
"{datapartition}-default-legal"
],
"otherRelevantDataCountries": [
"US"
],
"status": "compliant"
},
"tags": {
"NameOfKey": "String value"
},
"ancestry": {
"parents": []
},
"meta": [],
"data": {
"TechnicalAssurances": [
{
"TechnicalAssuranceTypeID": "{datapartition}:reference-data--TechnicalAssuranceType:Trusted:",
"Reviewers": [
{
"RoleTypeID": "{datapartition}:reference-data--ContactRoleType:AccountOwner:",
"Name": "Example Name"
}
],
"AcceptableUsage": [
{
"WorkflowUsage": "{datapartition}:reference-data--WorkflowUsageType:SeismicProcessing:",
"WorkflowPersona": "{datapartition}:reference-data--WorkflowPersonaType:SeismicProcessor:"
}
],
"UnacceptableUsage": [
{
"WorkflowUsage": "{datapartition}:reference-data--WorkflowUsageType:SeismicInterpretation:",
"WorkflowPersona": "{datapartition}:reference-data--WorkflowPersonaType:SeismicInterpreter:"
}
],
"EffectiveDate": "2020-02-13",
"Comment": "This is free form text from reviewer, e.g. restrictions on use"
}
],
"Name": "Example Name",
"relationships": {
"logs": {
"ids": [
"dataPartitionId:log1:",
"dataPartitionId:log2:"
]
}
},
"GeoContexts": [
{
"BasinID": "{datapartition}:master-data--Basin:1619c5b91aaf409d845a6e207cd13bff:",
"GeoTypeID": "{datapartition}:reference-data--BasinType:ArcWrenchOceanContinent:"
}
]
}
}
]Sample Data Workspace - Data Flow Status Processor Service response for a record containing invalid Related Record Ids
{
"results": [
{
"correlationId": "09807b7ab3a8a34e31c61d858cecf499",
"recordId": "{datapartition}:work-product-component--SeismicTraceData:99bee9abae4546099302a1bb46572f23",
"stage": "RELATIONSHIP_SYNC",
"status": "SUCCESS",
"message": "Processing of associated relationship and lineage entities is completed.",
"errorCode": 0,
"additionalProperties": {
"op": "create",
"noOfAssociatedRelationshipEntities": 1.0,
"reasonForFailure": "RecordId is not in valid format"
},
"userEmail": "39916b94-71a9-409e-856e-0f29558fa908",
"timestamp": 1734348271278
}
],
"count": 1,
"totalCount": 1,
"limit": 1
}