Skip to content

feat(specs): add analytics v3 pattern endpoints - #6795

Merged
Niamsy merged 13 commits into
mainfrom
feat/analytics/v3-pattern-endpoint
Aug 17, 2026
Merged

Niamsy merged 13 commits into
mainfrom
feat/analytics/v3-pattern-endpoint

Conversation

@Niamsy

@Niamsy Niamsy commented Jul 30, 2026

Copy link
Copy Markdown
Contributor

🧭 What and Why

Adds the semantic-patterns framework (/3/patterns/*) endpoints to the existing analytics client spec so it gets public clients generated. It's additive, no changes to /2/*.
Since these endpoints aren't fully stable yet, they're tagged beta (via the Patterns (Beta) tag + (Beta) summaries). They live in the existing analytics client rather than a dedicated v3 one, since they're additive.

Changes included:

  • specs/analytics/common/schemas/patterns.yml: payload/response/catalog schemas (+ limit/offset)
  • specs/analytics/paths/patterns/: getPatternsFields (GET) + queryPatterns{Timeseries,Scalar,Table,Distribution} (POST)
  • specs/analytics/spec.yml: wire the 5 paths, add pattern tag + group, note in version prose

πŸ§ͺ Test

  • Green CI

@algolia-api-clients-automation-bot

algolia-api-clients-automation-bot Bot commented Jul 30, 2026 •

Copy link
Copy Markdown
Contributor

βœ”οΈ Code generated!

Name Link
πŸͺ“ Triggered by a74f66c50456abf2872455071c898ddeb9ea99d3
πŸƒ Generated commit e6158c8c92483856afff486f0e4352c46193d666
🌲 Generated branch generated/feat/analytics/v3-pattern-endpoint
πŸ“Š Benchmark results

Benchmarks performed on the method using a mock server, the results might not reflect the real-world performance.

Language Req/s
javascript 2249
go 1821
php 1651
python 1396
csharp 1288
java 1081
ruby 971
scala 617
swift 605

@Niamsy
Niamsy requested a review from a team August 3, 2026 07:24
@Niamsy
Niamsy marked this pull request as ready for review August 3, 2026 07:24
@Niamsy
Niamsy requested a review from a team as a code owner August 3, 2026 07:24
@Niamsy
Niamsy requested review from Fluf22 and eric-zaharia August 3, 2026 07:24
Comment on lines +8 to +19
description: |
**Beta**: this endpoint is under active development and may change without notice.

Aggregates the requested `metrics` over the whole period and returns a single object keyed by metric
kind. `metrics` and `parameters` are required; `filters` is optional. Discover valid field kinds per
domain with `/3/patterns/fields`.
requestBody:
required: true
content:
application/json:
schema:
$ref: '../../common/schemas/patterns.yml#/ScalarPayload'

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me overall, and I don’t think this needs to block the PR. One thing to note:

  • These generated methods receive the indices through the request body.
  • The current Analytics backend performs index authorization earlier, using the index URL query parameter.
  • Unrestricted API keys work without that URL parameter.
  • With an index-restricted key, the consumer currently also needs to provide ?index=indexA,indexB through the generic request options.
  • For scalar, table, and timeseries, the backend then verifies that the URL and body indices match.

The generated client shape here looks reasonable, but restricted-key callers still have this non-obvious backend constraint.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the code to add the indices in the query param too (but not required)

Comment on lines +15 to +37
parameters:
- in: header
name: If-None-Match
required: false
description: Prior `ETag`. Returns `304 Not Modified` when the catalog is unchanged.
schema:
type: string
responses:
'200':
description: OK
headers:
x-ratelimit-limit:
$ref: '../../../common/responses/rateLimit.yml#/x-ratelimit-limit'
x-ratelimit-remaining:
$ref: '../../../common/responses/rateLimit.yml#/x-ratelimit-remaining'
x-ratelimit-reset:
$ref: '../../../common/responses/rateLimit.yml#/x-ratelimit-reset'
content:
application/json:
schema:
$ref: '../../common/schemas/patterns.yml#/Catalog'
'304':
description: Not Modified β€” the catalog matches the supplied `If-None-Match`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was looking into the caching behavior here because If-None-Match and 304 are different from how the other Analytics endpoints work. I think there may be a gap between what this method exposes and what the generated clients currently support:

  • The four query endpoints use backend Redis caching. Consumers always receive 200 and do not manage caching themselves.
  • This endpoint’s ETag flow requires the consumer to retrieve the ETag, store both the ETag and catalog, explicitly pass ifNoneMatch later, and reuse the stored catalog after a 304.
  • The generated client does not manage those steps automatically.
  • The generated JavaScript client does send If-None-Match when requested, but its transporter only treats 2xx responses as successful. It classifies a valid 304 as retryable and eventually throws, including from the HTTP-info method.

Given that the manual ETag flow is not currently supported end to end, would it be better to avoid exposing If-None-Match and 304 in the generated method for now?

Comment on lines +266 to +386
TimeseriesResponse:
type: object
title: Timeseries response
additionalProperties: false
properties:
series:
type: array
description: One entry per `groupBy` combination.
items:
title: series
type: object
additionalProperties: false
properties:
key:
type: object
description: The `groupBy` values identifying this series. Absent when the query has no `groupBy`.
additionalProperties: true
totals:
type: object
description: Metric totals over the whole period.
additionalProperties: true
dates:
type: array
description: Per-day metric breakdown.
items:
title: seriesDate
type: object
additionalProperties: false
properties:
date:
type: string
description: Day, formatted as YYYY-MM-DD.
metrics:
type: object
description: Metric values for the day.
additionalProperties: true

TableResponse:
type: object
title: Table response
additionalProperties: false
properties:
rows:
type: array
description: Result rows. Each row is a flat object of the requested fields.
items:
type: object
additionalProperties: true

ScalarResponse:
type: object
title: Scalar response
description: Object keyed by metric kind, each mapping to its aggregate value.
additionalProperties: true

DistributionResponse:
type: object
title: Distribution response
description: Object keyed by `histogram<Field>`, each mapping a bin label to a count.
additionalProperties: true

Catalog:
type: object
title: Field catalog
additionalProperties: false
properties:
domains:
type: object
description: Catalog entries grouped by domain.
additionalProperties:
$ref: '#/DomainCatalog'

DomainCatalog:
type: object
title: Domain catalog
additionalProperties: false
properties:
metrics:
type: array
description: Fields usable as metrics.
items:
$ref: '#/CatalogEntry'
filters:
type: array
description: Fields usable as filters.
items:
$ref: '#/CatalogEntry'
groups:
type: array
description: Fields usable in `groupBy`.
items:
$ref: '#/CatalogEntry'
distributions:
type: array
description: Fields usable in distributions.
items:
$ref: '#/CatalogEntry'

CatalogEntry:
type: object
title: Catalog entry
additionalProperties: false
required:
- kind
properties:
kind:
type: string
description: Field identifier.
description:
type: string
description: Human-readable description of the field.
roots:
type: array
description: Root stages the field depends on. Two fields are combinable in one query only when their roots intersect.
items:
type: string
requires:
type: array
description: Public ACL identifiers required to read the field, for example `clickAnalyticsEnabled`.
items:
type: string

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I noticed that the requiredness of these response models does not currently match what the Analytics backend serializes:

  • The backend always includes series, totals, dates, date, metrics, rows, domains, and the catalog arrays because those Go fields do not use omitempty.
  • key is the exception and is genuinely optional.
  • The current schemas do not mark the other fields as required, so generated clients model them as optional. For example, JavaScript generates rows?: ... and series?: ..., even though the backend does not omit those properties.
  • There is also a nullability difference for an empty timeseries. The backend currently leaves series as a nil slice and serializes "series": null, while this schema describes an optional, non-null array.

Could we align the response contract before publishing these models, including deciding whether an empty timeseries should return [] or null and marking the fields that are always present as required?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated to add the required to the field responses + made timeseries response nullable (I prefer matching the contract to the go code for now)

Comment on lines +1 to +43
get:
tags:
- pattern
operationId: getPatternsFields
x-acl:
- analytics
summary: (Beta) Retrieve the field catalog
description: |
**Beta**: this endpoint is under active development and may change without notice.

Returns the catalog of analytics fields available to the caller, grouped by domain and usage
(metrics, filters, groups, distributions). Use it to discover valid `(domain, kind)` pairs before
building the other `/3/patterns/*` queries. Two fields are combinable in one query only when their
`roots` intersect.
parameters:
- in: header
name: If-None-Match
required: false
description: Prior `ETag`. Returns `304 Not Modified` when the catalog is unchanged.
schema:
type: string
responses:
'200':
description: OK
headers:
x-ratelimit-limit:
$ref: '../../../common/responses/rateLimit.yml#/x-ratelimit-limit'
x-ratelimit-remaining:
$ref: '../../../common/responses/rateLimit.yml#/x-ratelimit-remaining'
x-ratelimit-reset:
$ref: '../../../common/responses/rateLimit.yml#/x-ratelimit-reset'
content:
application/json:
schema:
$ref: '../../common/schemas/patterns.yml#/Catalog'
'304':
description: Not Modified β€” the catalog matches the supplied `If-None-Match`.
'400':
$ref: '../../../common/responses/BadRequest.yml'
'402':
$ref: '../../../common/responses/FeatureNotEnabled.yml'
'403':
$ref: '../../../common/responses/MethodNotAllowed.yml'

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I noticed a difference between the contract described here and how the current Analytics backend registers this endpoint:

  • The backend registers /3/patterns/fields without the normal authentication or rate-limit middleware. It requires no application ID, API key, or Analytics ACL.
  • The handler returns the complete static catalog. Each catalog entry’s requires field explains the permissions needed when that field is later used in a query.
  • This specification inherits the Analytics API’s global application ID and API-key security and declares x-acl: analytics. The generated JavaScript documentation consequently says that the analytics ACL is required.
  • The response here declares the normal Analytics rate-limit headers, while the backend instead emits ETag and Cache-Control for this route.

Authenticated consumers can still call the endpoint because the additional credentials are harmless. The difference is that the backend presents it as an anonymous, cache-oriented discovery endpoint, while the generated contract presents it as an authenticated, rate-limited Analytics operation.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed the auth check for this route

@Niamsy
Niamsy requested a review from leonardogavaudan August 4, 2026 13:01
@Niamsy
Niamsy enabled auto-merge (squash) August 5, 2026 07:28

@eric-zaharia eric-zaharia left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@Niamsy
Niamsy disabled auto-merge August 5, 2026 08:47
@Niamsy
Niamsy enabled auto-merge (squash) August 5, 2026 08:47
@Niamsy
Niamsy disabled auto-merge August 17, 2026 12:26
@aikido-pr-checks

aikido-pr-checks Bot commented Aug 17, 2026 •

Copy link
Copy Markdown

Summary by Aikido

Security Issues: 0 Quality Issues: 0 Resolved Issues: 0

⚑ Enhancements

  • Increased JavaScript client bundle size limits for analytics and core builds

More info

@Niamsy
Niamsy merged commit 637defc into main Aug 17, 2026
70 of 72 checks passed
@Niamsy
Niamsy deleted the feat/analytics/v3-pattern-endpoint branch August 17, 2026 13:07
algolia-api-clients-automation-bot Bot added a commit that referenced this pull request Aug 17, 2026
…skip ci]

Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia-api-clients-automation-bot Bot added a commit to algolia/algoliasearch-client-csharp that referenced this pull request Aug 17, 2026
algolia/api-clients-automation#6795

Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com>
Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia-api-clients-automation-bot Bot added a commit to algolia/algoliasearch-client-go that referenced this pull request Aug 17, 2026
algolia/api-clients-automation#6795

Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com>
Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia-api-clients-automation-bot Bot added a commit to algolia/algoliasearch-client-java that referenced this pull request Aug 17, 2026
algolia/api-clients-automation#6795

Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com>
Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia-api-clients-automation-bot Bot added a commit to algolia/algoliasearch-client-javascript that referenced this pull request Aug 17, 2026
algolia/api-clients-automation#6795

Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com>
Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia-api-clients-automation-bot Bot added a commit to algolia/algoliasearch-client-kotlin that referenced this pull request Aug 17, 2026
algolia/api-clients-automation#6795

Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com>
Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia-api-clients-automation-bot Bot added a commit to algolia/algoliasearch-client-php that referenced this pull request Aug 17, 2026
algolia/api-clients-automation#6795

Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com>
Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia-api-clients-automation-bot Bot added a commit to algolia/algoliasearch-client-python that referenced this pull request Aug 17, 2026
algolia/api-clients-automation#6795

Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com>
Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia-api-clients-automation-bot Bot added a commit to algolia/algoliasearch-client-ruby that referenced this pull request Aug 17, 2026
algolia/api-clients-automation#6795

Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com>
Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia-api-clients-automation-bot Bot added a commit to algolia/algoliasearch-client-scala that referenced this pull request Aug 17, 2026
algolia/api-clients-automation#6795

Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com>
Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia-api-clients-automation-bot Bot added a commit to algolia/algoliasearch-client-swift that referenced this pull request Aug 17, 2026
algolia/api-clients-automation#6795

Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com>
Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants