Default APL query format to tabular

pr.md

@@ -0,0 +1,8 @@
+This switches `axiom-py` APL query defaults from `legacy` to `tabular` for both sync and async clients, aligning SDK behavior with the format migration plan.
+
+Slack context: <https://watchlyhq.slack.com/archives/C0ABV843Y9M/p1773440506177029|#gilfoyle-sessions thread>
+
+The change updates `AplOptions` defaults and both `_prepare_apl_options` code paths, while preserving explicit `format=AplResultFormat.Legacy` behavior for callers that still need it. Tests now assert the tabular default behavior directly.
+
+Validation:
+- `python3 -m pytest tests/test_query_defaults.py tests/test_client_async.py -q`

src/axiom_py/client.py

@@ -113,7 +113,7 @@ class AplOptions:
     # End time for the interval to query.
     end_time: Optional[datetime] = field(default=None)
     # The result format.
-    format: AplResultFormat = field(default=AplResultFormat.Legacy)
+    format: AplResultFormat = field(default=AplResultFormat.Tabular)
     # Cursor is the query cursor. It should be set to the Cursor returned with
     # a previous query result if it was partial.
     cursor: Optional[str] = field(default=None)
@@ -470,7 +470,7 @@ def _prepare_apl_options(
         self, opts: Optional[AplOptions]
     ) -> Dict[str, object]:
         """Prepare the apl query options for the request."""
-        params: Dict[str, object] = {"format": AplResultFormat.Legacy.value}
+        params: Dict[str, object] = {"format": AplResultFormat.Tabular.value}
 
         if opts is not None:
             if opts.format:

src/axiom_py/client_async.py

@@ -447,7 +447,7 @@ def _prepare_apl_options(
         """
         from .client import AplResultFormat
 
-        params: Dict[str, object] = {"format": AplResultFormat.Legacy.value}
+        params: Dict[str, object] = {"format": AplResultFormat.Tabular.value}
 
         if opts is not None:
             if opts.format:

tests/test_client_async.py

@@ -85,8 +85,9 @@ async def test_ingest_with_options(self):
 
     @respx.mock
     async def test_query(self):
-        """Test async APL query."""
+        """Test async APL query defaults to tabular format."""
         mock_response = {
+            "request": None,
             "status": {
                 "elapsedTime": 100,
                 "blocksExamined": 1,
@@ -97,18 +98,29 @@ async def test_query(self):
                 "minCursor": "0",
                 "maxCursor": "100",
             },
-            "matches": [
+            "matches": None,
+            "buckets": None,
+            "tables": [
                 {
-                    "_time": "2024-01-01T00:00:00Z",
-                    "_sysTime": "2024-01-01T00:00:00Z",
-                    "_rowId": "row-1",
-                    "data": {"field": "value", "count": 1},
+                    "buckets": None,
+                    "columns": [["value"]],
+                    "fields": [
+                        {
+                            "name": "field",
+                            "type": "string",
+                            "agg": None,
+                        }
+                    ],
+                    "groups": [],
+                    "name": "0",
+                    "order": [{"desc": False, "field": "_time"}],
+                    "range": None,
+                    "sources": [{"name": "test-dataset"}],
                 }
             ],
-            "buckets": {"series": [], "totals": []},
         }
 
-        respx.post("/v1/datasets/_apl").mock(
+        route = respx.post("/v1/datasets/_apl").mock(
             return_value=httpx.Response(
                 200,
                 json=mock_response,
@@ -120,10 +132,11 @@ async def test_query(self):
             token="test-token", url="http://localhost"
         ) as client:
             result = await client.query("['test-dataset'] | limit 100")
-            assert len(result.matches) == 1
-            assert result.matches[0].data["field"] == "value"
+            assert list(result.tables[0].events()) == [{"field": "value"}]
             assert result.savedQueryID == "query-123"
 
+        assert route.calls[0].request.url.params["format"] == "tabular"
+
     @respx.mock
     async def test_query_with_options(self):
         """Test APL query with options."""

tests/test_query_defaults.py

@@ -0,0 +1,15 @@
+from axiom_py import AplOptions, AplResultFormat, Client
+
+
+def test_apl_options_default_to_tabular():
+    opts = AplOptions()
+    assert opts.format == AplResultFormat.Tabular
+
+
+def test_client_prepare_apl_options_defaults_to_tabular():
+    client = Client(token="test-token", url="http://localhost")
+    try:
+        params = client._prepare_apl_options(None)
+        assert params["format"] == AplResultFormat.Tabular.value
+    finally:
+        client.shutdown_hook()