Skip to content
December 29, 2025

@MatrixVariable in Spring Boot: When and How to Use It

rajeshsgr · 3 min read · Containers

When designing REST APIs in Spring Boot, developers typically rely on path variables (/users/{id}) or query parameters (?filter=active). But Spring also supports a lesser-known, powerful feature: Matrix Variables.

Matrix variables allow you to attach key–value pairs directly to URL path segments using ;. This gives you more expressive, resource-centric URLs when parameters logically belong to a specific resource path segment rather than the whole request.

In this blog, we’ll cover:

  1. What matrix variables are.
  2. Practical examples with Spring Boot @MatrixVariable.
  3. Whether configuration is needed.
  4. When to use path variables vs query parameters vs matrix variables.

What Are Matrix Variables?

Matrix variables are parameters embedded in path segments.

/products/101;filter=active;view=summary
  • products/101 → Path segment
  • filter=active and view=summary → Matrix variables tied to 101

Unlike query parameters, which apply to the entire request, matrix variables apply only to the path segment they are attached to.

Example 1: Product Details with Filter and View

@GetMapping("/products/{productId}")
public String getProductDetails(
@PathVariable Long productId,
// Extract a single matrix variable 'filter'
@MatrixVariable(name = "filter") String filter,
// Extract a single matrix variable 'view' with a default value
@MatrixVariable(name = "view", defaultValue = "full") String view) {

return String.format(
"Fetching product ID: %d, applying filter: '%s', with view style: '%s'",
productId, filter, view
);
}

Request URL:

GET /products/101;filter=active;view=summary

Response:

Fetching product ID: 101, applying filter: 'active', with view style: 'summary'

If view is omitted:

GET /products/101;filter=active

Response:

Fetching product ID: 101, applying filter: 'active', with view style: 'full'

Example 2: Reports with Multiple Matrix Variables

Matrix variables also support multiple values and can differ across path segments.

@GetMapping("/reports/{quarter}/format/{formatType}")
public String getQuarterlyReport(
@PathVariable String quarter,
@PathVariable String formatType,
// Capture all matrix variables for the 'quarter' path segment
@MatrixVariable(pathVar = "quarter") Map<String, String> quarterParams,
// Capture a specific multi-value variable from 'formatType'
@MatrixVariable(pathVar = "formatType", name = "options") List<String> formatOptions) {

return String.format(
"Generating %s report (Format: %s). Quarter Params: %s. Format Options: %s",
quarter, formatType, quarterParams, formatOptions
);
}

Request URL:

GET /reports/Q3;status=pending,approved/format/csv;options=compact;options=secure

Response:

Generating Q3 report (Format: csv). Quarter Params: {status=pending,approved}. Format Options: [compact, secure]

Key Takeaways

  • Use Path Variables for resource identity.
  • Use Query Parameters for global filtering and options.
  • Use Matrix Variables for segment-specific parameters, especially when multiple path segments may each have their own metadata.
  • No config is needed in Spring Boot 3.x, but required in 2.x and older.

Matrix variables are a hidden gem in Spring Boot. They provide a clean way to make URLs more expressive and resource-focused — especially when parameters naturally belong to specific path segments.

Next time you design an API, ask yourself:

  • Does it identify the resource? → Path Variable
  • Is it a global filter? → Query Parameter
  • Is it tied to a specific path segment? → Matrix Variable

Designing with these distinctions will make your APIs more intuitive and RESTful.

Tags: , , ,

Leave a Reply