# JoinSpec.Builder

Artifact: [androidx.appsearch:appsearch](https://developer.android.com/jetpack/androidx/releases/appsearch) [View Source](https://cs.android.com/search?q=file:androidx/appsearch/app/JoinSpec.java+class:androidx.appsearch.app.JoinSpec.Builder) Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/appsearch#1.1.0)

*** ** * ** ***


```
public final class JoinSpec.Builder
```

<br />

*** ** * ** ***

Builder for `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec`.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec.Builder#Builder(java.lang.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html childPropertyExpression)` Create a specification for the joining operation in search. |
| `@https://developer.android.com/reference/androidx/appsearch/app/ExperimentalAppSearchApi https://developer.android.com/reference/androidx/appsearch/app/JoinSpec.Builder#Builder(androidx.appsearch.app.JoinSpec)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/appsearch/app/JoinSpec joinSpec)` Creates a new `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec.Builder` from the given `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec`. |

| ### Public methods |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/appsearch/app/JoinSpec` | `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec.Builder#build()()` Constructs a new `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec` from the contents of this builder. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/appsearch/app/JoinSpec.Builder` | `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec.Builder#setAggregationScoringStrategy(int)(int aggregationScoringStrategy)` Sets how we derive a single score from a list of joined documents. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/appsearch/app/JoinSpec.Builder` | `@https://developer.android.com/reference/androidx/appsearch/app/ExperimentalAppSearchApi https://developer.android.com/reference/androidx/appsearch/app/JoinSpec.Builder#setChildPropertyExpression(java.lang.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html childPropertyExpression)` Sets the child property expression. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/appsearch/app/JoinSpec.Builder` | `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec.Builder#setMaxJoinedResultCount(int)(int maxJoinedResultCount)` Sets the max amount of `https://developer.android.com/reference/androidx/appsearch/app/SearchResults` to return with the parent document, with a default of 10 SearchResults. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/appsearch/app/JoinSpec.Builder` | `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec.Builder#setNestedSearch(java.lang.String,androidx.appsearch.app.SearchSpec)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html nestedQuery, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/appsearch/app/SearchSpec nestedSearchSpec )` Sets the query and the SearchSpec for the documents being joined. |

## Public constructors

### Builder

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/appsearch#1.1.0)

```
public Builder(@NonNull String childPropertyExpression)
```

Create a specification for the joining operation in search.

The child property expression specifies how to join documents. Documents with a child property expression equal to the qualified id of the parent will be retrieved.

Property expressions differ from `https://developer.android.com/reference/androidx/appsearch/app/PropertyPath` as property expressions may refer to document properties or nested document properties such as "person.business.id" as well as a property expression. Currently the only property expression is "this.qualifiedId()". `https://developer.android.com/reference/androidx/appsearch/app/PropertyPath` objects may only reference document properties and nested document properties.

In order to join a child document to a parent document, the child document must contain the parent's qualified id at the property expression specified by this method.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html childPropertyExpression` | the property to match in the child documents. |

### Builder

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/appsearch#1.1.0)

```
@ExperimentalAppSearchApi
public Builder(@NonNull JoinSpec joinSpec)
```

Creates a new `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec.Builder` from the given `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec`.

## Public methods

### build

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/appsearch#1.1.0)

```
public @NonNull JoinSpec build()
```

Constructs a new `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec` from the contents of this builder.

### setAggregationScoringStrategy

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/appsearch#1.1.0)

```
public @NonNull JoinSpec.Builder setAggregationScoringStrategy(int aggregationScoringStrategy)
```

Sets how we derive a single score from a list of joined documents.

The default scoring strategy is `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec#AGGREGATION_SCORING_OUTER_RESULT_RANKING_SIGNAL()`, which specifies that the ranking signal of the outer parent document will be used.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/appsearch/app/SearchSpec#RANKING_STRATEGY_JOIN_AGGREGATE_SCORE()` |   |

### setChildPropertyExpression

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/appsearch#1.1.0)

```
@ExperimentalAppSearchApi
public @NonNull JoinSpec.Builder setChildPropertyExpression(@NonNull String childPropertyExpression)
```

Sets the child property expression.

The child property expression specifies how to join documents. Documents with a child property expression equal to the qualified id of the parent will be retrieved.

Property expressions differ from `https://developer.android.com/reference/androidx/appsearch/app/PropertyPath` as property expressions may refer to document properties or nested document properties such as "person.business.id" as well as a property expression. Currently the only property expression is "this.qualifiedId()". `https://developer.android.com/reference/androidx/appsearch/app/PropertyPath` objects may only reference document properties and nested document properties.

In order to join a child document to a parent document, the child document must contain the parent's qualified id at the property expression specified by this method.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html childPropertyExpression` | the property to match in the child documents. |

### setMaxJoinedResultCount

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/appsearch#1.1.0)

```
public @NonNull JoinSpec.Builder setMaxJoinedResultCount(int maxJoinedResultCount)
```

Sets the max amount of `https://developer.android.com/reference/androidx/appsearch/app/SearchResults` to return with the parent document, with a default of 10 SearchResults.

This does NOT limit the number of results that are joined with the parent document for scoring. This means that, when set, only a maximum of `maxJoinedResultCount` results will be returned with each parent document, but all results that are joined with a parent will factor into the score.

### setNestedSearch

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/appsearch#1.1.0)

```
public @NonNull JoinSpec.Builder setNestedSearch(
    @NonNull String nestedQuery,
    @NonNull SearchSpec nestedSearchSpec
)
```

Sets the query and the SearchSpec for the documents being joined. This will score and rank the joined documents as well as filter the joined documents.

If `https://developer.android.com/reference/androidx/appsearch/app/SearchSpec#RANKING_STRATEGY_JOIN_AGGREGATE_SCORE()` is set in the outer `https://developer.android.com/reference/androidx/appsearch/app/SearchSpec`, the resulting signals will be used to rank the parent documents. Note that the aggregation strategy also needs to be set with `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec.Builder#setAggregationScoringStrategy(int)`, otherwise the default will be `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec#AGGREGATION_SCORING_OUTER_RESULT_RANKING_SIGNAL()`, which will just use the parent documents ranking signal.

If this method is never called, `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec#getNestedQuery()` will return an empty string, meaning we will join with every possible document that matches the equality constraints and hasn't been filtered out by the type or namespace filters.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec#getNestedQuery()` |   |
| `https://developer.android.com/reference/androidx/appsearch/app/JoinSpec#getNestedSearchSpec()` |   |