feat(api): query meters v2 with filters

api/client/javascript/src/client/schemas.ts

@@ -9718,6 +9718,9 @@ export interface components {
     /** @description Client ID
      *     Useful to track progress of a query. */
     'MeterQuery.clientId': string
+    /** @description The filter for the events encoded as JSON string.
+     *     Can't be used together with `from`, `to`, `subject`, and `filterGroupBy`. */
+    'MeterQuery.filter': string
     /** @description Simple filter for group bys with exact match.
      *
      *     For example: ?filterGroupBy[vendor]=openai&filterGroupBy[model]=gpt-4-turbo */
@@ -10463,6 +10466,8 @@ export type ParameterMeterOrderByOrderingOrderBy =
   components['parameters']['MeterOrderByOrdering.orderBy']
 export type ParameterMeterQueryClientId =
   components['parameters']['MeterQuery.clientId']
+export type ParameterMeterQueryFilter =
+  components['parameters']['MeterQuery.filter']
 export type ParameterMeterQueryFilterGroupBy =
   components['parameters']['MeterQuery.filterGroupBy']
 export type ParameterMeterQueryFrom =
@@ -17425,6 +17430,11 @@ export interface operations {
          *
          *     For example: ?windowTimeZone=UTC */
         windowTimeZone?: components['parameters']['MeterQuery.windowTimeZone']
+        /** @description If not specified a single aggregate will be returned for each subject and time window.
+         *     `subject` is a reserved group by value.
+         *
+         *     For example: ?groupBy=subject&groupBy=model */
+        groupBy?: components['parameters']['MeterQuery.groupBy']
         /** @description Filtering by multiple subjects.
          *
          *     For example: ?subject=customer-1&subject=customer-2 */
@@ -17433,11 +17443,9 @@ export interface operations {
          *
          *     For example: ?filterGroupBy[vendor]=openai&filterGroupBy[model]=gpt-4-turbo */
         filterGroupBy?: components['parameters']['MeterQuery.filterGroupBy']
-        /** @description If not specified a single aggregate will be returned for each subject and time window.
-         *     `subject` is a reserved group by value.
-         *
-         *     For example: ?groupBy=subject&groupBy=model */
-        groupBy?: components['parameters']['MeterQuery.groupBy']
+        /** @description The filter for the events encoded as JSON string.
+         *     Can't be used together with `from`, `to`, `subject`, and `filterGroupBy`. */
+        filter?: components['parameters']['MeterQuery.filter']
       }
       header?: never
       path: {
@@ -20280,15 +20288,18 @@ export interface operations {
          *
          *     For example: ?windowTimeZone=UTC */
         windowTimeZone?: components['parameters']['MeterQuery.windowTimeZone']
-        /** @description Simple filter for group bys with exact match.
-         *
-         *     For example: ?filterGroupBy[vendor]=openai&filterGroupBy[model]=gpt-4-turbo */
-        filterGroupBy?: components['parameters']['MeterQuery.filterGroupBy']
         /** @description If not specified a single aggregate will be returned for each subject and time window.
          *     `subject` is a reserved group by value.
          *
          *     For example: ?groupBy=subject&groupBy=model */
         groupBy?: components['parameters']['MeterQuery.groupBy']
+        /** @description Simple filter for group bys with exact match.
+         *
+         *     For example: ?filterGroupBy[vendor]=openai&filterGroupBy[model]=gpt-4-turbo */
+        filterGroupBy?: components['parameters']['MeterQuery.filterGroupBy']
+        /** @description The filter for the events encoded as JSON string.
+         *     Can't be used together with `from`, `to`, `subject`, and `filterGroupBy`. */
+        filter?: components['parameters']['MeterQuery.filter']
       }
       header?: never
       path: {

api/openapi.cloud.yaml

@@ -5354,9 +5354,10 @@ paths:
         - $ref: '#/components/parameters/MeterQuery.to'
         - $ref: '#/components/parameters/MeterQuery.windowSize'
         - $ref: '#/components/parameters/MeterQuery.windowTimeZone'
+        - $ref: '#/components/parameters/MeterQuery.groupBy'
         - $ref: '#/components/parameters/MeterQuery.subject'
         - $ref: '#/components/parameters/MeterQuery.filterGroupBy'
-        - $ref: '#/components/parameters/MeterQuery.groupBy'
+        - $ref: '#/components/parameters/MeterQuery.filter'
       description: Query meter for usage.
       summary: Query meter
       responses:
@@ -7674,8 +7675,9 @@ paths:
         - $ref: '#/components/parameters/MeterQuery.to'
         - $ref: '#/components/parameters/MeterQuery.windowSize'
         - $ref: '#/components/parameters/MeterQuery.windowTimeZone'
-        - $ref: '#/components/parameters/MeterQuery.filterGroupBy'
         - $ref: '#/components/parameters/MeterQuery.groupBy'
+        - $ref: '#/components/parameters/MeterQuery.filterGroupBy'
+        - $ref: '#/components/parameters/MeterQuery.filter'
       description: Query meter for consumer portal. This endpoint is publicly exposable to consumers. Query meter for consumer portal. This endpoint is publicly exposable to consumers.
       summary: Query meter Query meter
       responses:
@@ -10617,6 +10619,28 @@ components:
         maxLength: 36
       explode: false
       style: form
+    MeterQuery.filter:
+      name: filter
+      in: query
+      required: false
+      description: |-
+        The filter for the events encoded as JSON string.
+        Can't be used together with `from`, `to`, `subject`, and `filterGroupBy`.
+      x-internal: true
+      content:
+        application/json:
+          schema:
+            properties:
+              groupBy:
+                type: object
+                additionalProperties:
+                  $ref: '#/components/schemas/FilterString'
+              subject:
+                $ref: '#/components/schemas/FilterString'
+              time:
+                $ref: '#/components/schemas/FilterTime'
+            x-internal: true
+            format: application/json
     MeterQuery.filterGroupBy:
       name: filterGroupBy
       in: query

api/openapi.yaml

@@ -5353,9 +5353,10 @@ paths:
         - $ref: '#/components/parameters/MeterQuery.to'
         - $ref: '#/components/parameters/MeterQuery.windowSize'
         - $ref: '#/components/parameters/MeterQuery.windowTimeZone'
+        - $ref: '#/components/parameters/MeterQuery.groupBy'
         - $ref: '#/components/parameters/MeterQuery.subject'
         - $ref: '#/components/parameters/MeterQuery.filterGroupBy'
-        - $ref: '#/components/parameters/MeterQuery.groupBy'
+        - $ref: '#/components/parameters/MeterQuery.filter'
       description: Query meter for usage.
       summary: Query meter
       responses:
@@ -7673,8 +7674,9 @@ paths:
         - $ref: '#/components/parameters/MeterQuery.to'
         - $ref: '#/components/parameters/MeterQuery.windowSize'
         - $ref: '#/components/parameters/MeterQuery.windowTimeZone'
-        - $ref: '#/components/parameters/MeterQuery.filterGroupBy'
         - $ref: '#/components/parameters/MeterQuery.groupBy'
+        - $ref: '#/components/parameters/MeterQuery.filterGroupBy'
+        - $ref: '#/components/parameters/MeterQuery.filter'
       description: Query meter for consumer portal. This endpoint is publicly exposable to consumers. Query meter for consumer portal. This endpoint is publicly exposable to consumers.
       summary: Query meter Query meter
       responses:
@@ -10359,6 +10361,28 @@ components:
         maxLength: 36
       explode: false
       style: form
+    MeterQuery.filter:
+      name: filter
+      in: query
+      required: false
+      description: |-
+        The filter for the events encoded as JSON string.
+        Can't be used together with `from`, `to`, `subject`, and `filterGroupBy`.
+      x-internal: true
+      content:
+        application/json:
+          schema:
+            properties:
+              groupBy:
+                type: object
+                additionalProperties:
+                  $ref: '#/components/schemas/FilterString'
+              subject:
+                $ref: '#/components/schemas/FilterString'
+              time:
+                $ref: '#/components/schemas/FilterTime'
+            x-internal: true
+            format: application/json
     MeterQuery.filterGroupBy:
       name: filterGroupBy
       in: query

api/spec/src/meters.tsp

@@ -353,6 +353,16 @@ model MeterQuery {
   @example("America/New_York")
   windowTimeZone?: string = "UTC";
 
+  /**
+   * If not specified a single aggregate will be returned for each subject and time window.
+   * `subject` is a reserved group by value.
+   *
+   * For example: ?groupBy=subject&groupBy=model
+   */
+  @query(#{ explode: true })
+  @example(#["model", "type"])
+  groupBy?: string[];
+
   /**
    * Filtering by multiple subjects.
    *
@@ -372,14 +382,27 @@ model MeterQuery {
   filterGroupBy?: Record<string>;
 
   /**
-   * If not specified a single aggregate will be returned for each subject and time window.
-   * `subject` is a reserved group by value.
-   *
-   * For example: ?groupBy=subject&groupBy=model
+   * The filter for the events encoded as JSON string.
+   * Can't be used together with `from`, `to`, `subject`, and `filterGroupBy`.
    */
-  @query(#{ explode: true })
-  @example(#["model", "type"])
-  groupBy?: string[];
+  @example(#{
+    groupBy: #{ `model`: #{ $eq: "gpt-4-turbo" }, type: #{ $eq: "prompt" } },
+    subject: #{ $eq: "my-event-subject" },
+    time: #{
+      $and: #[
+        #{ $gte: DateTime.fromISO("2025-01-01T00:00:00Z") },
+        #{ $lte: DateTime.fromISO("2025-01-02T00:00:00Z") }
+      ],
+    },
+  })
+  @query
+  @encode("application/json")
+  @extension("x-internal", true)
+  filter?: {
+    groupBy?: Record<OpenMeter.FilterString>;
+    subject?: OpenMeter.FilterString;
+    time?: OpenMeter.FilterTime;
+  };
 }
 
 /**

openmeter/meter/httphandler/mapping.go

@@ -8,8 +8,10 @@ import (
 	"github.com/samber/lo"
 
 	"github.com/openmeterio/openmeter/api"
+	"github.com/openmeterio/openmeter/openmeter/apiconverter"
 	"github.com/openmeterio/openmeter/openmeter/meter"
 	"github.com/openmeterio/openmeter/openmeter/streaming"
+	"github.com/openmeterio/openmeter/pkg/filter"
 	"github.com/openmeterio/openmeter/pkg/models"
 )
 
@@ -131,3 +133,54 @@ func ToQueryMeterParams(m meter.Meter, apiParams api.QueryMeterParams) (streamin
 
 	return params, nil
 }
+
+func ToQueryMeterParamsV2(m meter.Meter, apiParams api.QueryMeterParams) (streaming.QueryParamsV2, error) {
+	params := streaming.QueryParamsV2{
+		ClientID: apiParams.ClientId,
+	}
+
+	if apiParams.WindowSize != nil {
+		params.WindowSize = lo.ToPtr(meter.WindowSize(*apiParams.WindowSize))
+	}
+
+	if apiParams.WindowTimeZone != nil {
+		tz, err := time.LoadLocation(*apiParams.WindowTimeZone)
+		if err != nil {
+			err := fmt.Errorf("invalid time zone: %w", err)
+			return params, models.NewGenericValidationError(err)
+		}
+		params.WindowTimeZone = tz
+	}
+
+	if apiParams.GroupBy != nil {
+		for _, groupBy := range *apiParams.GroupBy {
+			// Validate group by, `subject` is a special group by
+			if ok := groupBy == "subject" || m.GroupBy[groupBy] != ""; !ok {
+				err := fmt.Errorf("invalid group by: %s", groupBy)
+				return params, models.NewGenericValidationError(err)
+			}
+
+			params.GroupBy = append(params.GroupBy, groupBy)
+		}
+	}
+
+	if apiParams.Filter != nil {
+		if apiParams.Filter.GroupBy != nil {
+			groupBy := map[string]filter.FilterString{}
+			for k, v := range *apiParams.Filter.GroupBy {
+				groupBy[k] = apiconverter.ConvertString(v)
+			}
+			params.Filter.GroupBy = &groupBy
+		}
+
+		params.Filter.Subject = apiconverter.ConvertStringPtr(apiParams.Filter.Subject)
+		params.Filter.Time = apiconverter.ConvertTimePtr(apiParams.Filter.Time)
+
+		// Add subject to group by if not already present
+		if params.Filter.Subject != nil && !slices.Contains(params.GroupBy, "subject") {
+			params.GroupBy = append(params.GroupBy, "subject")
+		}
+	}
+
+	return params, nil
+}