hibernate/hibernate-orm · error · UnsupportedOperationException

Index access is only supported for basic plural types.

Error message

Index access is only supported for basic plural types.

What it means

SqmFunctionPath.resolveIndexedAccess translates 'f(x)[i]' into an array_get call, but only when the function path's type is a BasicPluralType (an array of basic elements). For any other return type the operation throws UnsupportedOperationException because indexed access on non-basic-array function results has no SQL translation.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/sqm/tree/spi/domain/SqmFunctionPath.java:133

		creationState.getProcessingStateStack().getCurrent().getPathRegistry().register( sqmPath );
		return sqmPath;
	}

	@Override
	public SqmPath<?> resolveIndexedAccess(
			SqmExpression<?> selector,
			boolean isTerminal,
			SqmCreationState creationState) {
		final var pathRegistry = creationState.getCurrentProcessingState().getPathRegistry();
		final var navigablePath =
				getNavigablePath().append( CollectionPart.Nature.ELEMENT.getName(),
						selector.toHqlString() );
		final var indexedPath = pathRegistry.findFromByPath( navigablePath );
		if ( indexedPath != null ) {
			return indexedPath;
		}
		if ( !( getReferencedPathSource().getPathType() instanceof BasicPluralType<?, ?> ) ) {
			throw new UnsupportedOperationException( "Index access is only supported for basic plural types." );
		}
		final var queryEngine = creationState.getCreationContext().getQueryEngine();
		final SelfRenderingSqmFunction<?> result = queryEngine.getSqmFunctionRegistry()
				.getFunctionDescriptor( "array_get" )
				.generateSqmExpression(
						asList( function, selector ),
						null,
						queryEngine
				);
		final SqmFunctionPath<?> path = new SqmFunctionPath<>( result );
		pathRegistry.register( path );
		return path;
	}

	@Override
	public <X> X accept(SemanticQueryWalker<X> walker) {
		return walker.visitFunctionPath( this );
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Ensure the function is registered with a basic array return type (e.g. String[]/int[] resolved through the basic type registry) so the path type is a BasicPluralType
2. Use the explicit array_get(f(x), i) form once the return type is a proper basic array
3. Wrap the function result in cast(f(x) as String[]) to force a basic-array type before indexing
4. If you need elements of a structured collection, explode the value first (e.g. string_to_array/split into a typed array)

Example fix

// before: parse_names returns a plain String
select parse_names(p.csv)[1] from Person p
//  -> UnsupportedOperationException: Index access is only supported for basic plural types.

// after: register the function with String[] return type, then index it
registry.register("parse_names", new NamedSqmFunctionDescriptor(
    "parse_names", false, argTypes,
    StandardFunctionReturnTypeResolvers.instantiate(typeFactory.basicType(String[].class))));
select parse_names(p.csv)[1] from Person p

static boolean indexableFunctionResult(SqmFunctionPath<?> path) {
    return path.getReferencedPathSource().getPathType() instanceof BasicPluralType<?, ?>;
}

try {
    element = functionPath.resolveIndexedAccess(selector, true, creationState);
} catch (UnsupportedOperationException e) {
    // not a basic array: register the function with String[]/int[] return type, or use array_get on a typed array
    throw new IllegalStateException("Indexed access requires a basic-array-typed function", e);
}

When it happens

Trigger: HQL 'f(e.x)[1]' or criteria indexed access where the function returns a scalar, an embeddable, an entity, or a non-basic array type; e.g. indexing a function that returns a comma string instead of a typed array.

Common situations: Assuming [i] works on any function result after seeing Hibernate 6.6+/7 array indexing; functions returning custom array types without a registered array JdbcType; porting PostgreSQL-style subscripting into HQL.

Related errors

• Null return type for function: {}
• Unsupported return type for function: {}
• Embeddable paths cannot be TREAT-ed
• Entity discriminator cannot be de-referenced
• Entity discriminator cannot be de-referenced

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/0ecd66a1306bc76c. Report an issue: GitHub.