Module is.codion.framework.domain
Package is.codion.framework.domain.entity.attribute

Interface ForeignKey

All Superinterfaces:
Attribute<Entity>, ForeignKeyConditions
public sealed interface ForeignKey extends Attribute<Entity>, ForeignKeyConditions
An Attribute representing a foreign key relation.

Foreign keys establish relationships between entities, allowing navigation from one entity to related entities. They represent database foreign key constraints and enable automatic loading of referenced entities based on reference depth configuration.

Foreign keys inherit from ForeignKeyConditions to provide condition creation methods: 

interface Album {
	EntityType TYPE = DOMAIN.entityType("chinook.album");

	Column<Long> ID = TYPE.longColumn("id");
	Column<String> TITLE = TYPE.stringColumn("title");
	Column<Long> ARTIST_ID = TYPE.longColumn("artist_id");

	// Single-column foreign key
	ForeignKey ARTIST_FK = TYPE.foreignKey("artist_fk", ARTIST_ID, Artist.ID);
}

EntityDefinition album() {
	return Album.TYPE.as()
					.attributes(
									Album.ID.as()
													.primaryKey(),
									Album.TITLE.as()
													.column()
													.caption("Title"),
									Album.ARTIST_ID.as()
													.column(),
									Album.ARTIST_FK.as()
													.foreignKey()
													.caption("Artist")
													.referenceDepth(1)) // Load the artist automatically (1 is the default)
					.build();
}

void albums(EntityConnection connection) {
	// Foreign key navigation and usage
	List<Entity> albums = connection.select(all(Album.TYPE));

	for (Entity album : albums) {
		// Direct foreign key entity access (loaded automatically with reference depth)
		Entity artist = album.get(Album.ARTIST_FK);
		if (artist != null) {
			System.out.println("Artist: " + artist.get(Artist.NAME));
		}

		// Or use entity() to get the entity even if not loaded
		Entity artistEntity = album.entity(Album.ARTIST_FK);
		if (artistEntity != null) {
			Long artistId = artistEntity.get(Artist.ID); // Always available
		}
	}

	// Query conditions using foreign keys
	Entity acdc = connection.selectSingle(Artist.NAME.equalTo("AC/DC"));

	List<Entity> acdcAlbums = connection.select(
					Album.ARTIST_FK.equalTo(acdc));

	List<Entity> albumsByTheArtists = connection.select(
					Album.ARTIST_FK.in(connection.select(Artist.NAME.like("The %"))));
}
See Also: