LEXIO-37876 Adds richer metadata model to query resource (#2)

* LEXIO-37876 Adds richer metadata model to query resource

* Version bumped to 0.3.0

Co-authored-by: ns-circle-ci <devops-team+circleci@narrativescience.com>

Author: jdrake

crma_api_client/__init__.py

@@ -2,4 +2,4 @@
 
 from .client import CRMAAPIClient
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

crma_api_client/client.py

@@ -163,7 +163,7 @@ async def list_dataset_versions(self, identifier: str) -> DatasetVersionsRespons
             identifier: Dataset name or ID
 
         Returns:
-            DatasetVersionsResponse object
+            list of all versions for the dataset
 
         """
         response = await self.request(f"/wave/datasets/{identifier}/versions", "GET")
@@ -185,7 +185,7 @@ async def query(
             timezone: Timezone for the query
 
         Returns:
-            QueryResponse object
+            query results containing records and metadata
 
         """
         json_data = {

crma_api_client/resources/dataset.py

@@ -17,7 +17,10 @@ class Dataset(BaseModel):
 
 
 class DatasetVersion(BaseModel):
-    """Dataset version model"""
+    """Dataset version model
+
+    See https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataset_version.htm
+    """
 
     created_by: User
     created_date: datetime
@@ -36,7 +39,10 @@ class Config:
 
 
 class DatasetVersionsResponse(BaseModel):
-    """Response model for a list of dataset versions"""
+    """Response model for a list of dataset versions
+
+    See https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataset_version_collection.htm
+    """
 
     url: str
     versions: List[DatasetVersion]

crma_api_client/resources/query.py

@@ -16,21 +16,70 @@ class QueryLanguage(str, Enum):
     sql = "SQL"
 
 
+class ProjectionField(BaseModel):
+    """Field projected in the query result"""
+
+    id: str
+    type: str
+
+    @property
+    def name(self) -> str:
+        """Return field name that omits stream reference"""
+        return self.id.split(".")[-1]
+
+
+class LineageProjection(BaseModel):
+    """Field projection metadata container"""
+
+    field: ProjectionField
+
+
+class QueryLineage(BaseModel):
+    """Lineage that describes field projections in a query result"""
+
+    type: str
+    projections: List[LineageProjection]
+
+
+class QueryResultsMetadata(BaseModel):
+    """Query results metadata"""
+
+    lineage: QueryLineage
+    query_language: QueryLanguage
+
+    class Config:
+        """Model configuration"""
+
+        alias_generator = to_camel
+
+
 class QueryResults(BaseModel):
     """Query results model"""
 
+    metadata: List[QueryResultsMetadata]
     records: List[Dict[str, Any]]
 
 
 class QueryResponse(BaseModel):
-    """Response model for the query resource"""
+    """Response model for the query resource
+
+    See https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_query.htm
+    """
 
     action: str
     response_id: str
     results: QueryResults
     query: str
     response_time: int
 
+    @property
+    def fields(self) -> List[ProjectionField]:
+        """Return the fields from the query response metadata
+
+        This assumes there is only one metadata object and one lineage object.
+        """
+        return [p.field for p in self.results.metadata[0].lineage.projections]
+
     class Config:
         """Model configuration"""
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "crma-api-client"
-version = "0.2.0"
+version = "0.3.0"
 description = "CRM Analytics REST API Client"
 authors = ["Jonathan Drake <jon.drake@salesforce.com>"]
 license = "BSD-3-Clause"

tests/functional/test_query.py

@@ -3,6 +3,7 @@
 import pytest
 
 from crma_api_client.client import CRMAAPIClient
+from crma_api_client.resources.query import ProjectionField
 
 
 @pytest.mark.asyncio
@@ -24,3 +25,8 @@ async def test_query(client: CRMAAPIClient):
         {"Category": "Office Supplies", "Sales": 719047.032},
         {"Category": "Technology", "Sales": 836154.033},
     ]
+    assert response.fields == [
+        ProjectionField(id="q.Category", type="string"),
+        ProjectionField(id="q.Sales", type="numeric"),
+    ]
+    assert response.fields[0].name == "Category"