From 115e29adc35abb9b894c63dd9556db9d8e6348cd Mon Sep 17 00:00:00 2001
From: Marcos Lopez Gonzalez <marcoslg@gmail.com>
Date: Fri, 14 Jun 2024 12:40:06 +0200
Subject: [PATCH] #140 fallback lang suggest

---
 .../vocabulary/persistence/dto/ParentDto.java |   5 +-
 .../persistence/dto/SuggestDto.java           |  10 +-
 .../handlers/LanguageRegionTypeHandler.java   |  16 +-
 .../persistence/mappers/ConceptMapper.java    |   9 +-
 .../persistence/mappers/VocabularyMapper.java |   8 +-
 .../vocabulary/service/ConceptService.java    |  17 +-
 .../vocabulary/service/VocabularyService.java |   9 +-
 .../service/impl/DefaultConceptService.java   |  96 ++++-------
 .../impl/DefaultVocabularyService.java        |  24 ++-
 .../persistence/mappers/ConceptMapper.xml     | 157 ++++++++++--------
 .../persistence/mappers/VocabularyMapper.xml  | 117 +++++++++----
 .../mappers/ConceptMapperTest.java            |  78 +++++----
 .../mappers/VocabularyMapperTest.java         |  51 ++++--
 .../vocabulary/service/ConceptServiceIT.java  |  96 ++++++-----
 .../service/VocabularyServiceIT.java          |  65 ++++++++
 .../model/search/KeyNameResult.java           |  15 --
 .../model/search/SuggestResult.java           |  23 +++
 .../model/search/KeyNameResultTest.java       |   2 -
 .../gbif/vocabulary/client/ConceptClient.java |   1 +
 .../vocabulary/client/VocabularyClient.java   |  10 +-
 .../restws/resources/ConceptResource.java     |  20 ++-
 .../restws/resources/VocabularyResource.java  |  11 +-
 .../restws/resources/ConceptResourceIT.java   |   3 +-
 .../resources/mock/BaseResourceTest.java      |  18 +-
 .../resources/mock/ConceptResourceTest.java   |   7 +-
 .../mock/VocabularyResourceTest.java          |   6 +-
 26 files changed, 562 insertions(+), 312 deletions(-)
 create mode 100644 model/src/main/java/org/gbif/vocabulary/model/search/SuggestResult.java

diff --git a/core/src/main/java/org/gbif/vocabulary/persistence/dto/ParentDto.java b/core/src/main/java/org/gbif/vocabulary/persistence/dto/ParentDto.java
index d640eab7..cf9e50c2 100644
--- a/core/src/main/java/org/gbif/vocabulary/persistence/dto/ParentDto.java
+++ b/core/src/main/java/org/gbif/vocabulary/persistence/dto/ParentDto.java
@@ -9,7 +9,8 @@ public class ParentDto {
   long key;
   String name;
   int depth;
-  Long labelKey;
+  String label;
   LanguageRegion labelLanguage;
-  String labelValue;
+  String fallbackLabel;
+  LanguageRegion fallbackLabelLanguage;
 }
diff --git a/core/src/main/java/org/gbif/vocabulary/persistence/dto/SuggestDto.java b/core/src/main/java/org/gbif/vocabulary/persistence/dto/SuggestDto.java
index 15d4b41b..b8bafd84 100644
--- a/core/src/main/java/org/gbif/vocabulary/persistence/dto/SuggestDto.java
+++ b/core/src/main/java/org/gbif/vocabulary/persistence/dto/SuggestDto.java
@@ -1,16 +1,18 @@
 package org.gbif.vocabulary.persistence.dto;
 
-import org.gbif.vocabulary.model.Label;
+import lombok.Data;
+import org.gbif.vocabulary.model.LanguageRegion;
 
 import java.util.List;
 
-import lombok.Data;
-
 @Data
 public class SuggestDto {
 
   private long key;
+  private LanguageRegion langParam;
+  private LanguageRegion fallbackLangParam;
   private String name;
-  private List<Label> labels;
+  private String label;
+  private LanguageRegion labelLang;
   private List<ParentDto> parentDtos;
 }
diff --git a/core/src/main/java/org/gbif/vocabulary/persistence/handlers/LanguageRegionTypeHandler.java b/core/src/main/java/org/gbif/vocabulary/persistence/handlers/LanguageRegionTypeHandler.java
index e91af41e..0a6e619b 100644
--- a/core/src/main/java/org/gbif/vocabulary/persistence/handlers/LanguageRegionTypeHandler.java
+++ b/core/src/main/java/org/gbif/vocabulary/persistence/handlers/LanguageRegionTypeHandler.java
@@ -24,6 +24,8 @@
 import org.apache.ibatis.type.MappedTypes;
 import org.apache.ibatis.type.TypeHandler;
 
+import com.google.common.base.Strings;
+
 @MappedTypes({LanguageRegion.class})
 public class LanguageRegionTypeHandler implements TypeHandler<LanguageRegion> {
 
@@ -36,16 +38,24 @@ public void setParameter(
 
   @Override
   public LanguageRegion getResult(ResultSet rs, String columnName) throws SQLException {
-    return LanguageRegion.fromLocale(rs.getString(columnName));
+    return convertResult(rs.getString(columnName));
   }
 
   @Override
   public LanguageRegion getResult(ResultSet rs, int columnIndex) throws SQLException {
-    return LanguageRegion.fromLocale(rs.getString(columnIndex));
+    return convertResult(rs.getString(columnIndex));
   }
 
   @Override
   public LanguageRegion getResult(CallableStatement cs, int columnIndex) throws SQLException {
-    return LanguageRegion.fromLocale(cs.getString(columnIndex));
+    return convertResult(cs.getString(columnIndex));
+  }
+
+  private LanguageRegion convertResult(String value) {
+    if (Strings.isNullOrEmpty(value)) {
+      return null;
+    }
+
+    return LanguageRegion.fromLocale(value);
   }
 }
diff --git a/core/src/main/java/org/gbif/vocabulary/persistence/mappers/ConceptMapper.java b/core/src/main/java/org/gbif/vocabulary/persistence/mappers/ConceptMapper.java
index b7404ff1..bf17be3e 100644
--- a/core/src/main/java/org/gbif/vocabulary/persistence/mappers/ConceptMapper.java
+++ b/core/src/main/java/org/gbif/vocabulary/persistence/mappers/ConceptMapper.java
@@ -23,6 +23,7 @@
 import org.gbif.vocabulary.model.search.ChildrenResult;
 import org.gbif.vocabulary.model.search.ConceptSearchParams;
 import org.gbif.vocabulary.model.search.KeyNameResult;
+import org.gbif.vocabulary.persistence.dto.SuggestDto;
 
 import java.util.List;
 
@@ -31,8 +32,6 @@
 import org.apache.ibatis.annotations.Mapper;
 import org.apache.ibatis.annotations.Param;
 
-import org.gbif.vocabulary.persistence.dto.SuggestDto;
-
 /** Mapper for {@link Concept}. */
 @Mapper
 public interface ConceptMapper extends BaseMapper<Concept> {
@@ -59,7 +58,8 @@ List<SuggestDto> suggest(
       @Param("query") String query,
       @Param("vocabularyKey") long vocabularyKey,
       @Nullable @Param("lang") LanguageRegion language,
-      @Nullable @Param("fallbackLang") LanguageRegion fallbackLang);
+      @Nullable @Param("fallbackLang") LanguageRegion fallbackLang,
+      @Param("limit") int limit);
 
   /**
    * Given a deprecated concept, it finds the current replacement, that's to say, the first
@@ -156,7 +156,8 @@ List<SuggestDto> suggestLatestRelease(
       @Param("vocabularyKey") long vocabularyKey,
       @Nullable @Param("lang") LanguageRegion languageFilter,
       @Nullable @Param("fallbackLang") LanguageRegion fallbackLang,
-      @Param("vocabName") String vocabularyName);
+      @Param("vocabName") String vocabularyName,
+      @Param("limit") int limit);
 
   List<String> findParentsLatestRelease(
       @Param("key") long conceptKey, @Param("vocabName") String vocabularyName);
diff --git a/core/src/main/java/org/gbif/vocabulary/persistence/mappers/VocabularyMapper.java b/core/src/main/java/org/gbif/vocabulary/persistence/mappers/VocabularyMapper.java
index 61b224d1..1b56e4f4 100644
--- a/core/src/main/java/org/gbif/vocabulary/persistence/mappers/VocabularyMapper.java
+++ b/core/src/main/java/org/gbif/vocabulary/persistence/mappers/VocabularyMapper.java
@@ -18,6 +18,7 @@
 import org.gbif.vocabulary.model.Vocabulary;
 import org.gbif.vocabulary.model.search.KeyNameResult;
 import org.gbif.vocabulary.model.search.VocabularySearchParams;
+import org.gbif.vocabulary.persistence.dto.SuggestDto;
 
 import java.util.List;
 
@@ -40,8 +41,11 @@ List<Vocabulary> list(
 
   Long getKeyByName(@Param("name") String name);
 
-  List<KeyNameResult> suggest(
-      @Param("query") String query, @Nullable @Param("lang") LanguageRegion language);
+  List<SuggestDto> suggest(
+      @Param("query") String query,
+      @Nullable @Param("lang") LanguageRegion language,
+      @Nullable @Param("fallbackLang") LanguageRegion fallbackLang,
+      @Param("limit") int limit);
 
   /**
    * Searches for a similar vocabulary whose name or any of its labels are the same as the ones
diff --git a/core/src/main/java/org/gbif/vocabulary/service/ConceptService.java b/core/src/main/java/org/gbif/vocabulary/service/ConceptService.java
index 99eb2726..430d900f 100644
--- a/core/src/main/java/org/gbif/vocabulary/service/ConceptService.java
+++ b/core/src/main/java/org/gbif/vocabulary/service/ConceptService.java
@@ -23,7 +23,7 @@
 import org.gbif.vocabulary.model.Tag;
 import org.gbif.vocabulary.model.search.ChildrenResult;
 import org.gbif.vocabulary.model.search.ConceptSearchParams;
-import org.gbif.vocabulary.model.search.KeyNameResult;
+import org.gbif.vocabulary.model.search.SuggestResult;
 
 import java.util.List;
 
@@ -61,13 +61,15 @@ public interface ConceptService extends BaseService<Concept> {
    * @param vocabularyKey key of the vocabulary
    * @param languageRegion locale to filter by
    * @param fallbackLanguageRegion fallback locale to show in the response
+   * @param limit to limit the results, up to 20
    * @return a list of up to 20 suggested concepts
    */
-  List<KeyNameResult> suggest(
+  List<SuggestResult> suggest(
       String query,
       long vocabularyKey,
       @Nullable LanguageRegion languageRegion,
-      @Nullable LanguageRegion fallbackLanguageRegion);
+      @Nullable LanguageRegion fallbackLanguageRegion,
+      @Nullable Integer limit);
 
   /**
    * Deprecates a concept with a replacement.
@@ -187,15 +189,16 @@ PagingResponse<Concept> listLatestRelease(
       @Nullable ConceptSearchParams params, @Nullable Pageable page, String vocabularyName);
 
   /**
-   * It works as {@link #suggest(String, long, LanguageRegion, LanguageRegion)} but it queries the
-   * latest release of the vocabulary instead of the actual data.
+   * It works as {@link #suggest(String, long, LanguageRegion, LanguageRegion, Integer)} but it
+   * queries the latest release of the vocabulary instead of the actual data.
    */
-  List<KeyNameResult> suggestLatestRelease(
+  List<SuggestResult> suggestLatestRelease(
       String query,
       long vocabularyKey,
       @Nullable LanguageRegion languageRegion,
       @Nullable LanguageRegion fallbackLanguageRegion,
-      String vocabularyName);
+      String vocabularyName,
+      Integer limit);
 
   /**
    * It works as {@link #getByNameAndVocabulary(String, String)} but it queries the latest release
diff --git a/core/src/main/java/org/gbif/vocabulary/service/VocabularyService.java b/core/src/main/java/org/gbif/vocabulary/service/VocabularyService.java
index 476742ec..9d9a353c 100644
--- a/core/src/main/java/org/gbif/vocabulary/service/VocabularyService.java
+++ b/core/src/main/java/org/gbif/vocabulary/service/VocabularyService.java
@@ -18,6 +18,7 @@
 import org.gbif.vocabulary.model.LanguageRegion;
 import org.gbif.vocabulary.model.Vocabulary;
 import org.gbif.vocabulary.model.search.KeyNameResult;
+import org.gbif.vocabulary.model.search.SuggestResult;
 import org.gbif.vocabulary.model.search.VocabularySearchParams;
 
 import java.util.List;
@@ -52,9 +53,15 @@ public interface VocabularyService extends BaseService<Vocabulary> {
    *
    * @param query suggestion
    * @param languageRegion locale to filter by
+   * @param fallbackLanguageRegion fallback locale to show in the response
+   * @param limit to limit the results, up to 20
    * @return a list of up to 20 suggested vocabularies
    */
-  List<KeyNameResult> suggest(String query, @Nullable LanguageRegion languageRegion);
+  List<SuggestResult> suggest(
+      String query,
+      @Nullable LanguageRegion languageRegion,
+      @Nullable LanguageRegion fallbackLanguageRegion,
+      @Nullable Integer limit);
 
   /**
    * Deprecates a vocabulary with a replacement.
diff --git a/core/src/main/java/org/gbif/vocabulary/service/impl/DefaultConceptService.java b/core/src/main/java/org/gbif/vocabulary/service/impl/DefaultConceptService.java
index c08929b7..40045ce0 100644
--- a/core/src/main/java/org/gbif/vocabulary/service/impl/DefaultConceptService.java
+++ b/core/src/main/java/org/gbif/vocabulary/service/impl/DefaultConceptService.java
@@ -26,6 +26,7 @@
 import org.gbif.vocabulary.model.search.ChildrenResult;
 import org.gbif.vocabulary.model.search.ConceptSearchParams;
 import org.gbif.vocabulary.model.search.KeyNameResult;
+import org.gbif.vocabulary.model.search.SuggestResult;
 import org.gbif.vocabulary.model.utils.PostPersist;
 import org.gbif.vocabulary.model.utils.PrePersist;
 import org.gbif.vocabulary.persistence.dto.ParentDto;
@@ -38,7 +39,6 @@
 import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
-import java.util.function.Function;
 import java.util.stream.Collectors;
 
 import javax.annotation.Nullable;
@@ -68,6 +68,7 @@
 @Validated
 public class DefaultConceptService implements ConceptService {
 
+  private static final int DEFAULT_SUGGEST_LIMIT = 20;
   private final ConceptMapper conceptMapper;
   private final VocabularyMapper vocabularyMapper;
 
@@ -177,80 +178,44 @@ public PagingResponse<Concept> list(
   }
 
   @Override
-  public List<KeyNameResult> suggest(
+  public List<SuggestResult> suggest(
       String query,
       long vocabularyKey,
       @Nullable LanguageRegion languageRegion,
-      @Nullable LanguageRegion fallbackLanguageRegion) {
+      @Nullable LanguageRegion fallbackLanguageRegion,
+      Integer limit) {
     query = query != null ? query : "";
+    limit = limit != null ? limit : DEFAULT_SUGGEST_LIMIT;
     List<SuggestDto> dtos =
-        conceptMapper.suggest(query, vocabularyKey, languageRegion, fallbackLanguageRegion);
-
-    return convertSuggestResults(languageRegion, fallbackLanguageRegion, dtos);
+        conceptMapper.suggest(query, vocabularyKey, languageRegion, fallbackLanguageRegion, limit);
+    return convertSuggestResults(dtos);
   }
 
-  private static List<KeyNameResult> convertSuggestResults(
-      LanguageRegion languageRegion, LanguageRegion fallbackLanguageRegion, List<SuggestDto> dtos) {
+  private static List<SuggestResult> convertSuggestResults(List<SuggestDto> dtos) {
     return dtos.stream()
         .map(
             dto -> {
-              KeyNameResult keyNameResult = new KeyNameResult();
-              keyNameResult.setKey(dto.getKey());
-              keyNameResult.setName(dto.getName());
-              keyNameResult.setLabels(dto.getLabels());
-
-              Function<List<Label>, List<Label>> filterLabels =
-                  labels -> {
-                    if (languageRegion != null && fallbackLanguageRegion != null) {
-                      // keep only the ones of the language requested if they exist
-                      List<Label> langLabels =
-                          labels.stream()
-                              .filter(l -> l.getLanguage().equals(languageRegion))
-                              .collect(Collectors.toList());
-
-                      if (!langLabels.isEmpty()) {
-                        return langLabels;
-                      }
-                    }
-                    return labels;
-                  };
-
-              keyNameResult.setLabels(filterLabels.apply(dto.getLabels()));
-
-              keyNameResult.setParents(
+              SuggestResult suggestResult = new SuggestResult();
+              suggestResult.setName(dto.getName());
+              suggestResult.setLabel(dto.getLabel());
+              suggestResult.setLabelLanguage(dto.getLabelLang());
+              suggestResult.setParents(
                   dto.getParentDtos().stream()
-                      .collect(
-                          Collectors.toMap(
-                              ParentDto::getKey,
-                              p -> {
-                                KeyNameResult.Parent parent = new KeyNameResult.Parent();
-                                parent.setKey(p.getKey());
-                                parent.setName(p.getName());
-                                parent.setDepth(p.getDepth());
-                                Label label =
-                                    Label.builder()
-                                        .key(p.getLabelKey())
-                                        .value(p.getLabelValue())
-                                        .language(p.getLabelLanguage())
-                                        .build();
-                                parent.getLabels().add(label);
-                                return parent;
-                              },
-                              (p1, p2) -> {
-                                p1.getLabels().addAll(p2.getLabels());
-                                return p1;
-                              }))
-                      .values()
-                      .stream()
+                      .sorted(Comparator.comparing(ParentDto::getDepth))
                       .map(
                           p -> {
-                            p.setLabels(filterLabels.apply(p.getLabels()));
-                            return p;
+                            SuggestResult.Parent parent = new SuggestResult.Parent();
+                            parent.setName(p.getName());
+                            parent.setLabel(
+                                p.getLabel() != null ? p.getLabel() : p.getFallbackLabel());
+                            parent.setLabelLanguage(
+                                p.getLabelLanguage() != null
+                                    ? p.getLabelLanguage()
+                                    : p.getFallbackLabelLanguage());
+                            return parent;
                           })
-                      .sorted(Comparator.comparing(KeyNameResult.Parent::getDepth))
                       .collect(Collectors.toList()));
-
-              return keyNameResult;
+              return suggestResult;
             })
         .collect(Collectors.toList());
   }
@@ -555,25 +520,28 @@ public PagingResponse<Concept> listLatestRelease(
   }
 
   @Override
-  public List<KeyNameResult> suggestLatestRelease(
+  public List<SuggestResult> suggestLatestRelease(
       String query,
       long vocabularyKey,
       LanguageRegion languageRegion,
       LanguageRegion fallbackLanguageRegion,
-      String vocabularyName) {
+      String vocabularyName,
+      Integer limit) {
     checkArgument(!Strings.isNullOrEmpty(vocabularyName));
     checkArgument(conceptMapper.existsReleaseView(vocabularyName.toLowerCase()));
 
     query = query != null ? query : "";
+    limit = limit != null ? limit : DEFAULT_SUGGEST_LIMIT;
     List<SuggestDto> dtos =
         conceptMapper.suggestLatestRelease(
             query,
             vocabularyKey,
             languageRegion,
             fallbackLanguageRegion,
-            vocabularyName.toLowerCase());
+            vocabularyName.toLowerCase(),
+            limit);
 
-    return convertSuggestResults(languageRegion, fallbackLanguageRegion, dtos);
+    return convertSuggestResults(dtos);
   }
 
   @Override
diff --git a/core/src/main/java/org/gbif/vocabulary/service/impl/DefaultVocabularyService.java b/core/src/main/java/org/gbif/vocabulary/service/impl/DefaultVocabularyService.java
index 1ae7dee7..86e587fa 100644
--- a/core/src/main/java/org/gbif/vocabulary/service/impl/DefaultVocabularyService.java
+++ b/core/src/main/java/org/gbif/vocabulary/service/impl/DefaultVocabularyService.java
@@ -24,9 +24,11 @@
 import org.gbif.vocabulary.model.Vocabulary;
 import org.gbif.vocabulary.model.search.ConceptSearchParams;
 import org.gbif.vocabulary.model.search.KeyNameResult;
+import org.gbif.vocabulary.model.search.SuggestResult;
 import org.gbif.vocabulary.model.search.VocabularySearchParams;
 import org.gbif.vocabulary.model.utils.PostPersist;
 import org.gbif.vocabulary.model.utils.PrePersist;
+import org.gbif.vocabulary.persistence.dto.SuggestDto;
 import org.gbif.vocabulary.persistence.mappers.ConceptMapper;
 import org.gbif.vocabulary.persistence.mappers.VocabularyMapper;
 import org.gbif.vocabulary.persistence.mappers.VocabularyReleaseMapper;
@@ -59,6 +61,7 @@
 @Validated
 public class DefaultVocabularyService implements VocabularyService {
 
+  private static final int DEFAULT_SUGGEST_LIMIT = 20;
   private final VocabularyMapper vocabularyMapper;
   private final ConceptMapper conceptMapper;
   private final VocabularyReleaseMapper vocabularyReleaseMapper;
@@ -202,9 +205,26 @@ public PagingResponse<Vocabulary> list(VocabularySearchParams params, Pageable p
   }
 
   @Override
-  public List<KeyNameResult> suggest(String query, @Nullable LanguageRegion languageRegion) {
+  public List<SuggestResult> suggest(
+      String query,
+      @Nullable LanguageRegion languageRegion,
+      @Nullable LanguageRegion fallbackLanguageRegion,
+      Integer limit) {
     query = query != null ? query : "";
-    return vocabularyMapper.suggest(query, languageRegion);
+    limit = limit != null ? limit : DEFAULT_SUGGEST_LIMIT;
+    List<SuggestDto> dtos =
+        vocabularyMapper.suggest(query, languageRegion, fallbackLanguageRegion, limit);
+
+    return dtos.stream()
+        .map(
+            dto -> {
+              SuggestResult suggestResult = new SuggestResult();
+              suggestResult.setName(dto.getName());
+              suggestResult.setLabel(dto.getLabel());
+              suggestResult.setLabelLanguage(dto.getLabelLang());
+              return suggestResult;
+            })
+        .collect(Collectors.toList());
   }
 
   @Secured({UserRoles.VOCABULARY_ADMIN, UserRoles.VOCABULARY_EDITOR})
diff --git a/core/src/main/resources/org/gbif/vocabulary/persistence/mappers/ConceptMapper.xml b/core/src/main/resources/org/gbif/vocabulary/persistence/mappers/ConceptMapper.xml
index b16eba8d..b6f46d72 100644
--- a/core/src/main/resources/org/gbif/vocabulary/persistence/mappers/ConceptMapper.xml
+++ b/core/src/main/resources/org/gbif/vocabulary/persistence/mappers/ConceptMapper.xml
@@ -12,10 +12,10 @@
     <collection property="label" column="{entityKey=key}" select="listConceptLabels"/>
   </resultMap>
 
-  <resultMap id="KEY_NAME_RESULT_MAP" type="SuggestDto" autoMapping="true">
+  <resultMap id="SUGGEST_RESULT_MAP" type="SuggestDto" autoMapping="true">
     <id property="key" column="key"/>
-    <collection property="labels" column="{entityKey=key,lang=lang,fallbackLang=fallbackLang}" select="listConceptLabels"/>
-    <collection property="parentDtos" column="{key=key,lang=lang,fallbackLang=fallbackLang}" select="findParentsLabels"/>
+    <collection property="parentDtos" column="{key=key,lang=langParam,fallbackLang=fallbackLangParam}"
+                select="findParentsLabels"/>
   </resultMap>
 
   <resultMap id="DEFINITION_RESULT_MAP" type="Definition" autoMapping="true">
@@ -31,6 +31,7 @@
   <resultMap id="PARENT_RESULT_MAP" type="ParentDto" autoMapping="true">
     <id property="key" column="key"/>
     <result property="labelLanguage" column="labelLanguage" typeHandler="LanguageRegionTypeHandler"/>
+    <result property="fallbackLabelLanguage" column="fallbackLabelLanguage" typeHandler="LanguageRegionTypeHandler"/>
   </resultMap>
 
   <resultMap id="HIDDEN_LABEL_RESULT_MAP" type="HiddenLabel" autoMapping="true">
@@ -149,51 +150,91 @@
   </sql>
 
   <sql id="SUGGEST">
-    SELECT DISTINCT ON(key) key, name, #{lang} lang
-      <if test="_parameter.containsKey('fallbackLang')">,#{fallbackLang} fallbackLang</if>
+    SELECT DISTINCT ON(key) key, name, label, labelLang
+      <if test="_parameter.containsKey('lang')">,#{lang} langParam</if>
+      <if test="_parameter.containsKey('fallbackLang')">,#{fallbackLang} fallbackLangParam</if>
       <if test="_parameter.containsKey('vocabName')">, #{vocabName} vocabName</if>
     FROM (
-      (SELECT key, name
-      FROM concept${table_suffix}
-      WHERE vocabulary_key = #{vocabularyKey} AND
-      name ilike #{query}||'%' AND deprecated IS NULL
-      ORDER BY name LIMIT 20 )
-    UNION ALL
-      (SELECT key, name
-      FROM concept${table_suffix}
-      WHERE vocabulary_key = #{vocabularyKey} AND name ilike '%'||#{query}||'%' AND NOT name ilike
-      #{query}||'%' AND deprecated IS NULL
-      ORDER BY name LIMIT 20 )
+    (
+      SELECT c.key AS key, c.name AS name, cl.value AS label, cl.language AS labelLang
+      FROM concept${table_suffix} c
+      INNER JOIN concept_label${table_suffix} cl ON cl.concept_key = c.key
+      WHERE c.vocabulary_key = #{vocabularyKey} AND c.deprecated IS NULL
+      AND cl.value ilike #{query}||'%' <if test="lang != null">AND cl.language = #{lang}</if>
+      ORDER BY cl.value
+      LIMIT #{limit}
+    )
+    <if test="lang != null and fallbackLang != null">
+      UNION ALL
+      (
+        SELECT c.key AS key, c.name AS name, cl.value AS label, cl.language AS labelLang
+        FROM concept${table_suffix} c
+        INNER JOIN concept_label${table_suffix} cl ON cl.concept_key = c.key
+        WHERE c.vocabulary_key = #{vocabularyKey} AND c.deprecated IS NULL
+        AND cl.value ilike #{query}||'%' AND cl.language = #{fallbackLang}
+        AND NOT EXISTS (
+        SELECT * FROM concept_label cl2 WHERE cl2.concept_key = c.key AND cl2.language = #{lang}
+        )
+        ORDER BY cl.value
+        LIMIT #{limit}
+      )
+    </if>
     UNION ALL
-      (SELECT DISTINCT c.key, c.name
+    (
+      SELECT c.key AS key, c.name AS name, NULL AS label, NULL AS labelLang
       FROM concept${table_suffix} c
-      JOIN concept_label${table_suffix} cl ON cl.concept_key = c.key
-      WHERE c.vocabulary_key = #{vocabularyKey} AND cl.value ilike #{query}||'%' AND c.deprecated IS NULL
+      WHERE c.vocabulary_key = #{vocabularyKey} AND c.deprecated IS NULL
+      AND c.name ilike #{query}||'%'
       <if test="lang != null">
-        AND cl.language = #{lang}
+        AND NOT EXISTS (
+          SELECT * FROM concept_label cl WHERE cl.concept_key = c.key
+          AND cl.language IN (#{lang}<if test="fallbackLang != null">,#{fallbackLang}</if>)
+        )
       </if>
-      LIMIT 20 )
+      ORDER BY c.name
+      LIMIT #{limit}
+    )
     UNION ALL
-      (SELECT DISTINCT c.key, c.name
+    (
+      SELECT c.key AS key, c.name AS name, cl.value AS label, cl.language AS labelLang
       FROM concept${table_suffix} c
-      JOIN concept_label${table_suffix} cl ON cl.concept_key = c.key
-      WHERE c.vocabulary_key = #{vocabularyKey} AND cl.value ilike '%'||#{query}||'%' AND NOT cl.value ilike #{query}||'%'
-      AND c.deprecated IS NULL
-      <if test="lang != null">
-        AND cl.language = #{lang}
-      </if>
-      LIMIT 20 )
-    <if test="fallbackLang != null">
+      INNER JOIN concept_label${table_suffix} cl ON cl.concept_key = c.key
+      WHERE c.vocabulary_key = #{vocabularyKey} AND c.deprecated IS NULL
+      AND cl.value ilike '%'||#{query}||'%' <if test="lang != null">AND cl.language = #{lang}</if>
+      ORDER BY cl.value
+      LIMIT #{limit}
+    )
+    <if test="lang != null and fallbackLang != null">
       UNION ALL
-        (SELECT DISTINCT c.key, c.name
+      (
+        SELECT c.key AS key, c.name AS name, cl.value AS label, cl.language AS labelLang
         FROM concept${table_suffix} c
-        JOIN concept_label${table_suffix} cl ON cl.concept_key = c.key
-        WHERE c.vocabulary_key = #{vocabularyKey} AND cl.value ilike #{query}||'%'
-        AND c.deprecated IS NULL
-        AND cl.language = #{fallbackLang}
-        LIMIT 20 )
+        INNER JOIN concept_label${table_suffix} cl ON cl.concept_key = c.key
+        WHERE c.vocabulary_key = #{vocabularyKey} AND c.deprecated IS NULL
+        AND cl.value ilike '%'||#{query}||'%' AND cl.language = #{fallbackLang}
+        AND NOT EXISTS (
+        SELECT * FROM concept_label cl2 WHERE cl2.concept_key = c.key AND cl2.language = #{lang}
+        )
+        ORDER BY cl.value
+        LIMIT #{limit}
+      )
     </if>
-    ) t1 LIMIT 20
+    UNION ALL
+    (
+      SELECT c.key AS key, c.name AS name, NULL AS label, NULL AS labelLang
+      FROM concept${table_suffix} c
+      WHERE c.vocabulary_key = #{vocabularyKey} AND c.deprecated IS NULL
+      AND c.name ilike '%'||#{query}||'%'
+      <if test="lang != null">
+        AND NOT EXISTS (
+        SELECT * FROM concept_label cl WHERE cl.concept_key = c.key
+        AND cl.language IN (#{lang}<if test="fallbackLang != null">,#{fallbackLang}</if>)
+        )
+      </if>
+      ORDER BY c.name
+     LIMIT #{limit}
+     )
+    ) t1 LIMIT #{limit}
   </sql>
 
   <sql id="COUNT_CHILDREN">
@@ -229,19 +270,16 @@
     SELECT c.key, c.name, c.parent_key, c.deprecated, p.depth + 1
     FROM parents p, concept${table_suffix} c
     WHERE p.parent_key = c.key )
-    SELECT p.key, p.name, p.depth , cl.key AS labelKey, cl.language AS labelLanguage, cl.value AS labelValue
+    SELECT p.key, p.name, p.depth
+      <if test="lang != null">, cl.value AS label, cl.language AS labelLanguage</if>
+      <if test="fallbackLang != null">, clf.value AS fallbackLabel, clf.language AS fallbackLabelLanguage</if>
     FROM parents p
-    LEFT JOIN concept_label${table_suffix} cl ON cl.concept_key = p.key
-      <if test="lang != null or fallbackLang != null">
-        AND (
-        <if test="lang != null">
-          cl.language = #{lang}
-        </if>
-        <if test="fallbackLang != null">
-          OR cl.language = #{fallbackLang}
-        </if>
-        )
-      </if>
+    <if test="lang != null">
+      LEFT JOIN concept_label${table_suffix} cl ON cl.concept_key = p.key AND cl.language = #{lang}
+    </if>
+    <if test="fallbackLang != null">
+      LEFT JOIN concept_label${table_suffix} clf ON clf.concept_key = p.key AND clf.language = #{fallbackLang}
+    </if>
     WHERE p.key != #{key,jdbcType=BIGINT};
   </sql>
 
@@ -257,16 +295,6 @@
     FROM concept_label${table_suffix}
     <where>
       concept_key = #{entityKey,jdbcType=BIGINT}
-      <if test="lang != null or fallbackLang != null">
-        AND (
-        <if test="lang != null">
-          language = #{lang}
-        </if>
-        <if test="fallbackLang != null">
-          OR language = #{fallbackLang}
-        </if>
-        )
-      </if>
     </where>
     ORDER BY key DESC
   </sql>
@@ -435,7 +463,7 @@
     <include refid="LIST_COMMON"/>
   </select>
 
-  <select id="suggest" resultMap="KEY_NAME_RESULT_MAP">
+  <select id="suggest" resultMap="SUGGEST_RESULT_MAP">
     <bind name="table_suffix" value="''"/>
     <include refid="SUGGEST"/>
   </select>
@@ -729,7 +757,7 @@
     <include refid="LIST_COMMON"/>
   </select>
 
-  <select id="suggestLatestRelease" resultMap="KEY_NAME_RESULT_MAP_RELEASE_VIEW">
+  <select id="suggestLatestRelease" resultMap="SUGGEST_RESULT_MAP_RELEASE_VIEW">
     <bind name="table_suffix" value="'_' + _parameter.vocabName + '_latest_release_mv'"/>
     <include refid="SUGGEST"/>
   </select>
@@ -805,11 +833,10 @@
     <collection property="label" column="{entityKey=key,vocabName=vocabName}" select="listConceptLabelsLatestRelease"/>
   </resultMap>
 
-  <resultMap id="KEY_NAME_RESULT_MAP_RELEASE_VIEW" type="SuggestDto" autoMapping="true">
+  <resultMap id="SUGGEST_RESULT_MAP_RELEASE_VIEW" type="SuggestDto" autoMapping="true">
     <id property="key" column="key"/>
-    <collection property="labels" column="{entityKey=key,vocabName=vocabName,lang=lang,fallbackLang=fallbackLang}"
-                select="listConceptLabelsLatestRelease"/>
-    <collection property="parentDtos" column="{key=key,lang=lang,fallbackLang=fallbackLang}" select="findParentsLabelsLatestRelease"/>
+    <collection property="parentDtos" column="{key=key,lang=langParam,fallbackLang=fallbackLangParam}"
+                select="findParentsLabelsLatestRelease"/>
   </resultMap>
 
 
diff --git a/core/src/main/resources/org/gbif/vocabulary/persistence/mappers/VocabularyMapper.xml b/core/src/main/resources/org/gbif/vocabulary/persistence/mappers/VocabularyMapper.xml
index b0a062a7..b3b55052 100644
--- a/core/src/main/resources/org/gbif/vocabulary/persistence/mappers/VocabularyMapper.xml
+++ b/core/src/main/resources/org/gbif/vocabulary/persistence/mappers/VocabularyMapper.xml
@@ -10,9 +10,8 @@
     <collection property="label" column="key" select="listVocabularyLabels"/>
   </resultMap>
 
-  <resultMap id="KEY_NAME_RESULT_MAP" type="KeyNameResult" autoMapping="true">
+  <resultMap id="SUGGEST_RESULT_MAP" type="SuggestDto" autoMapping="true">
     <id property="key" column="key"/>
-    <collection property="labels" column="key" select="listVocabularyLabels"/>
   </resultMap>
 
   <resultMap id="LABEL_RESULT_MAP" type="Label" autoMapping="true">
@@ -192,41 +191,91 @@
     </where>
   </select>
 
-  <select id="suggest" resultMap="KEY_NAME_RESULT_MAP">
-    SELECT DISTINCT ON(key) key, name
+  <select id="suggest" resultMap="SUGGEST_RESULT_MAP">
+    SELECT DISTINCT ON(key) key, name, label, labelLang
     FROM (
-      (SELECT key, name
-      FROM vocabulary
-      WHERE name ilike #{query}||'%' AND deprecated IS NULL
-      ORDER BY name LIMIT 20
+      (
+        SELECT v.key, v.name, vl.value AS label, vl.language AS labelLang
+        FROM vocabulary v
+        JOIN vocabulary_label vl ON vl.vocabulary_key = v.key
+        WHERE vl.value ilike #{query}||'%' AND v.deprecated IS NULL
+        <if test="lang != null">
+          AND vl.language = #{lang}
+        </if>
+        ORDER BY vl.value
+        LIMIT #{limit}
       )
-    UNION ALL
-      (SELECT key, name
-      FROM vocabulary
-      WHERE name ilike '%'||#{query}||'%' AND NOT name ilike #{query}||'%' AND deprecated IS NULL
-      ORDER BY name LIMIT 20
+    <if test="lang != null and fallbackLang != null">
+      UNION ALL
+      (
+        SELECT v.key, v.name, vl.value AS label, vl.language AS labelLang
+        FROM vocabulary v
+        JOIN vocabulary_label vl ON vl.vocabulary_key = v.key
+        WHERE vl.value ilike #{query}||'%' AND v.deprecated IS NULL AND vl.language = #{fallbackLang}
+        AND NOT EXISTS (
+          SELECT * FROM vocabulary_label vl2 WHERE vl2.vocabulary_key = v.key AND vl2.language = #{lang}
+        )
+        ORDER BY vl.value
+        LIMIT #{limit}
       )
-    UNION ALL
-      (SELECT DISTINCT v.key, v.name
-      FROM vocabulary v
-      JOIN vocabulary_label vl ON vl.vocabulary_key = v.key
-      WHERE vl.value ilike #{query}||'%' AND v.deprecated IS NULL
-    <if test="lang != null">
-      AND vl.language = #{lang}
-    </if>
-    LIMIT 20
-    )
-    UNION ALL
-    (SELECT DISTINCT v.key, v.name
-    FROM vocabulary v
-    JOIN vocabulary_label vl ON vl.vocabulary_key = v.key
-    WHERE vl.value ilike '%'||#{query}||'%' AND NOT vl.value ilike #{query}||'%' AND v.deprecated IS NULL
-    <if test="lang != null">
-      AND vl.language= #{lang}
     </if>
-    LIMIT 20
-    )
-    ) t1 LIMIT 20
+      UNION ALL
+      (
+        SELECT v.key AS key, v.name AS name, NULL AS label, NULL AS labelLang
+        FROM vocabulary v
+        WHERE v.deprecated IS NULL
+        AND v.name ilike #{query}||'%'
+        <if test="lang != null">
+          AND NOT EXISTS (
+          SELECT * FROM vocabulary_label vl WHERE vl.vocabulary_key = v.key
+          AND vl.language IN (#{lang}<if test="fallbackLang != null">,#{fallbackLang}</if>)
+          )
+        </if>
+        ORDER BY v.name
+        LIMIT #{limit}
+      )
+      UNION ALL
+      (
+        SELECT v.key, v.name, vl.value AS label, vl.language AS labelLang
+        FROM vocabulary v
+        JOIN vocabulary_label vl ON vl.vocabulary_key = v.key
+        WHERE vl.value ilike '%'||#{query}||'%' AND v.deprecated IS NULL
+        <if test="lang != null">
+          AND vl.language = #{lang}
+        </if>
+        ORDER BY vl.value
+        LIMIT #{limit}
+      )
+      <if test="lang != null and fallbackLang != null">
+        UNION ALL
+        (
+          SELECT v.key, v.name, vl.value AS label, vl.language AS labelLang
+          FROM vocabulary v
+          JOIN vocabulary_label vl ON vl.vocabulary_key = v.key
+          WHERE vl.value ilike '%'||#{query}||'%' AND v.deprecated IS NULL AND vl.language = #{fallbackLang}
+          AND NOT EXISTS (
+          SELECT * FROM vocabulary_label vl2 WHERE vl2.vocabulary_key = v.key AND vl2.language = #{lang}
+          )
+          ORDER BY vl.value
+          LIMIT #{limit}
+        )
+      </if>
+      UNION ALL
+      (
+        SELECT v.key AS key, v.name AS name, NULL AS label, NULL AS labelLang
+        FROM vocabulary v
+        WHERE v.deprecated IS NULL
+        AND v.name ilike '%'||#{query}||'%'
+        <if test="lang != null">
+          AND NOT EXISTS (
+          SELECT * FROM vocabulary_label vl WHERE vl.vocabulary_key = v.key
+          AND vl.language IN (#{lang}<if test="fallbackLang != null">,#{fallbackLang}</if>)
+          )
+        </if>
+        ORDER BY v.name
+        LIMIT #{limit}
+        )
+    ) t1 LIMIT #{limit}
   </select>
 
   <select id="findSimilarities" resultType="KeyNameResult">
@@ -363,4 +412,4 @@
     ORDER BY created DESC
   </select>
 
-</mapper>
\ No newline at end of file
+</mapper>
diff --git a/core/src/test/java/org/gbif/vocabulary/persistence/mappers/ConceptMapperTest.java b/core/src/test/java/org/gbif/vocabulary/persistence/mappers/ConceptMapperTest.java
index c2077ace..0c39db71 100644
--- a/core/src/test/java/org/gbif/vocabulary/persistence/mappers/ConceptMapperTest.java
+++ b/core/src/test/java/org/gbif/vocabulary/persistence/mappers/ConceptMapperTest.java
@@ -65,6 +65,7 @@
 @ContextConfiguration(initializers = {ConceptMapperTest.ContextInitializer.class})
 public class ConceptMapperTest extends BaseMapperTest<Concept> {
 
+  private static final int DEFAULT_SUGGEST_LIMIT = 20;
   private static final String DEFAULT_VOCABULARY = "Default";
 
   private static final Vocabulary[] vocabularies = new Vocabulary[2];
@@ -214,11 +215,6 @@ public void suggestTest() {
             .createdBy("test")
             .build());
 
-    conceptMapper.addHiddenLabel(
-        c1.getKey(), HiddenLabel.builder().value("lab,l").createdBy("test").build());
-    conceptMapper.addHiddenLabel(
-        c1.getKey(), HiddenLabel.builder().value("lbel").createdBy("test").build());
-
     Concept c2 = createNewEntity();
     c2.setName("Suggest222");
 
@@ -229,16 +225,15 @@ public void suggestTest() {
         c2.getKey(),
         Label.builder().language(LanguageRegion.ENGLISH).value("Label").createdBy("test").build());
 
-    conceptMapper.addHiddenLabel(
-        c2.getKey(), HiddenLabel.builder().value("lab,l").createdBy("test").build());
-    conceptMapper.addHiddenLabel(
-        c2.getKey(), HiddenLabel.builder().value("lbel").createdBy("test").build());
-
     // check result values
-    List<SuggestDto> result = conceptMapper.suggest("suggest1", c1.getVocabularyKey(), null, null);
+    List<SuggestDto> result =
+        conceptMapper.suggest("suggest1", c1.getVocabularyKey(), null, null, DEFAULT_SUGGEST_LIMIT);
     assertEquals("Suggest111", result.get(0).getName());
     assertEquals(c1.getKey().intValue(), result.get(0).getKey());
 
+    result = conceptMapper.suggest("su", c1.getVocabularyKey(), null, null, 1);
+    assertEquals(1, result.size());
+
     // create release view to test it at the same time
     conceptMapper.createLatestReleaseView(
         DEFAULT_VOCABULARY.toLowerCase(), vocabularies[0].getKey());
@@ -254,8 +249,8 @@ public void suggestTest() {
     assertSuggest(0, "labeleng", c1.getVocabularyKey(), LanguageRegion.SPANISH, null);
     assertSuggest(1, "labeleng", c1.getVocabularyKey(), LanguageRegion.ENGLISH, null);
     // should get fallback lang
-    assertSuggest(2, "su", c1.getVocabularyKey(), LanguageRegion.ARPITAN, LanguageRegion.ENGLISH);
-    assertSuggest(2, "su", c1.getVocabularyKey(), LanguageRegion.ARPITAN, LanguageRegion.SPANISH);
+    assertSuggest(0, "su", c1.getVocabularyKey(), LanguageRegion.ARPITAN, LanguageRegion.ENGLISH);
+    assertSuggest(1, "su", c1.getVocabularyKey(), LanguageRegion.ARPITAN, LanguageRegion.SPANISH);
     assertSuggest(2, "su", c1.getVocabularyKey(), LanguageRegion.ARPITAN, LanguageRegion.AFRIKAANS);
 
     Concept c3 = createNewEntity();
@@ -264,10 +259,26 @@ public void suggestTest() {
     conceptMapper.create(c3);
     assertNotNull(c3.getKey());
 
-    assertEquals(2, conceptMapper.suggest("su", c1.getVocabularyKey(), null, null).size());
-    assertEquals(1, conceptMapper.suggest("su", c3.getVocabularyKey(), null, null).size());
-    assertEquals(1, conceptMapper.suggest("33", c3.getVocabularyKey(), null, null).size());
-    assertEquals(0, conceptMapper.suggest("33", c1.getVocabularyKey(), null, null).size());
+    assertEquals(
+        2,
+        conceptMapper
+            .suggest("su", c1.getVocabularyKey(), null, null, DEFAULT_SUGGEST_LIMIT)
+            .size());
+    assertEquals(
+        1,
+        conceptMapper
+            .suggest("su", c3.getVocabularyKey(), null, null, DEFAULT_SUGGEST_LIMIT)
+            .size());
+    assertEquals(
+        1,
+        conceptMapper
+            .suggest("33", c3.getVocabularyKey(), null, null, DEFAULT_SUGGEST_LIMIT)
+            .size());
+    assertEquals(
+        0,
+        conceptMapper
+            .suggest("33", c1.getVocabularyKey(), null, null, DEFAULT_SUGGEST_LIMIT)
+            .size());
   }
 
   private void assertSuggest(
@@ -276,10 +287,12 @@ private void assertSuggest(
       long vocabKey,
       LanguageRegion lang,
       LanguageRegion fallbackLang) {
-    List<SuggestDto> result = conceptMapper.suggest(query, vocabKey, lang, fallbackLang);
+    List<SuggestDto> result =
+        conceptMapper.suggest(query, vocabKey, lang, fallbackLang, DEFAULT_SUGGEST_LIMIT);
     assertEquals(expectedSize, result.size());
     List<SuggestDto> resultRelease =
-        conceptMapper.suggestLatestRelease(query, vocabKey, lang, fallbackLang, DEFAULT_VOCABULARY);
+        conceptMapper.suggestLatestRelease(
+            query, vocabKey, lang, fallbackLang, DEFAULT_VOCABULARY, DEFAULT_SUGGEST_LIMIT);
     assertEquals(expectedSize, resultRelease.size());
 
     if (lang != null) {
@@ -287,12 +300,9 @@ private void assertSuggest(
           result.stream()
               .allMatch(
                   r ->
-                      r.getLabels() == null
-                          || r.getLabels().isEmpty()
-                          || r.getLabels().stream()
-                              .allMatch(
-                                  l ->
-                                      l.getLanguage() == lang || l.getLanguage() == fallbackLang)));
+                      r.getLabelLang() == null
+                          || r.getLabelLang() == lang
+                          || (fallbackLang != null && r.getLabelLang() == fallbackLang)));
     }
   }
 
@@ -1014,8 +1024,13 @@ public void releaseViewSubqueriesTest() {
 
     List<SuggestDto> suggestResult =
         conceptMapper.suggestLatestRelease(
-            concept1.getName(), concept1.getVocabularyKey(), null, null, vocabName);
-    assertEquals(0, suggestResult.get(0).getLabels().size());
+            concept1.getName(),
+            concept1.getVocabularyKey(),
+            null,
+            null,
+            vocabName,
+            DEFAULT_SUGGEST_LIMIT);
+    assertNull(suggestResult.get(0).getLabel());
 
     conceptMapper.updateReleaseViews(vocabName);
 
@@ -1033,8 +1048,13 @@ public void releaseViewSubqueriesTest() {
 
     suggestResult =
         conceptMapper.suggestLatestRelease(
-            concept1.getName(), concept1.getVocabularyKey(), null, null, vocabName);
-    assertEquals(1, suggestResult.get(0).getLabels().size());
+            concept1.getName(),
+            concept1.getVocabularyKey(),
+            null,
+            null,
+            vocabName,
+            DEFAULT_SUGGEST_LIMIT);
+    assertNull(suggestResult.get(0).getLabel());
   }
 
   @Test
diff --git a/core/src/test/java/org/gbif/vocabulary/persistence/mappers/VocabularyMapperTest.java b/core/src/test/java/org/gbif/vocabulary/persistence/mappers/VocabularyMapperTest.java
index b3d7ea7d..8d32e7d2 100644
--- a/core/src/test/java/org/gbif/vocabulary/persistence/mappers/VocabularyMapperTest.java
+++ b/core/src/test/java/org/gbif/vocabulary/persistence/mappers/VocabularyMapperTest.java
@@ -22,6 +22,7 @@
 import org.gbif.vocabulary.model.VocabularyRelease;
 import org.gbif.vocabulary.model.search.KeyNameResult;
 import org.gbif.vocabulary.model.search.VocabularySearchParams;
+import org.gbif.vocabulary.persistence.dto.SuggestDto;
 
 import java.net.URI;
 import java.util.ArrayList;
@@ -52,6 +53,7 @@
 @ContextConfiguration(initializers = {VocabularyMapperTest.ContextInitializer.class})
 public class VocabularyMapperTest extends BaseMapperTest<Vocabulary> {
 
+  private static final int DEFAULT_SUGGEST_LIMIT = 20;
   private final VocabularyMapper vocabularyMapper;
   private final ConceptMapper conceptMapper;
   private final VocabularyReleaseMapper vocabularyReleaseMapper;
@@ -229,20 +231,47 @@ public void suggestTest() {
         Label.builder().language(LanguageRegion.ENGLISH).value("Label").createdBy("test").build());
 
     // check result values
-    List<KeyNameResult> result = vocabularyMapper.suggest("suggest1", null);
+    List<SuggestDto> result =
+        vocabularyMapper.suggest("suggest1", null, null, DEFAULT_SUGGEST_LIMIT);
     assertEquals("Suggest111", result.get(0).getName());
-    assertEquals(v1.getKey().intValue(), result.get(0).getKey());
+    assertEquals(v1.getKey(), result.get(0).getKey());
 
     // assert expected number of results
-    assertEquals(2, vocabularyMapper.suggest("su", null).size());
-    assertEquals(2, vocabularyMapper.suggest("gge", null).size());
-    assertEquals(1, vocabularyMapper.suggest("22", null).size());
-    assertEquals(0, vocabularyMapper.suggest("zz", null).size());
-    assertEquals(0, vocabularyMapper.suggest(null, null).size());
-    assertEquals(2, vocabularyMapper.suggest("label", null).size());
-    assertEquals(1, vocabularyMapper.suggest("labeleng", null).size());
-    assertEquals(0, vocabularyMapper.suggest("labeleng", LanguageRegion.SPANISH).size());
-    assertEquals(1, vocabularyMapper.suggest("labeleng", LanguageRegion.ENGLISH).size());
+    assertEquals(2, vocabularyMapper.suggest("su", null, null, DEFAULT_SUGGEST_LIMIT).size());
+    assertEquals(2, vocabularyMapper.suggest("gge", null, null, DEFAULT_SUGGEST_LIMIT).size());
+    assertEquals(1, vocabularyMapper.suggest("22", null, null, DEFAULT_SUGGEST_LIMIT).size());
+    assertEquals(0, vocabularyMapper.suggest("zz", null, null, DEFAULT_SUGGEST_LIMIT).size());
+    assertEquals(0, vocabularyMapper.suggest(null, null, null, DEFAULT_SUGGEST_LIMIT).size());
+    assertEquals(2, vocabularyMapper.suggest("label", null, null, DEFAULT_SUGGEST_LIMIT).size());
+    assertEquals(1, vocabularyMapper.suggest("labeleng", null, null, DEFAULT_SUGGEST_LIMIT).size());
+    assertEquals(
+        0,
+        vocabularyMapper
+            .suggest("labeleng", LanguageRegion.SPANISH, null, DEFAULT_SUGGEST_LIMIT)
+            .size());
+    assertEquals(
+        1,
+        vocabularyMapper
+            .suggest("label", LanguageRegion.SPANISH, null, DEFAULT_SUGGEST_LIMIT)
+            .size());
+    assertEquals(
+        1,
+        vocabularyMapper
+            .suggest("labeleng", LanguageRegion.ENGLISH, null, DEFAULT_SUGGEST_LIMIT)
+            .size());
+
+    List<SuggestDto> dtos =
+        vocabularyMapper.suggest(
+            "label", LanguageRegion.SPANISH, LanguageRegion.ENGLISH, DEFAULT_SUGGEST_LIMIT);
+    assertEquals(2, dtos.size());
+    dtos.forEach(
+        dto -> {
+          if (dto.getName().equals(v2.getName())) {
+            assertEquals(LanguageRegion.ENGLISH, dto.getLabelLang());
+          } else {
+            assertEquals(LanguageRegion.SPANISH, dto.getLabelLang());
+          }
+        });
   }
 
   @Test
diff --git a/core/src/test/java/org/gbif/vocabulary/service/ConceptServiceIT.java b/core/src/test/java/org/gbif/vocabulary/service/ConceptServiceIT.java
index a4cda2d4..a6ec2f5e 100644
--- a/core/src/test/java/org/gbif/vocabulary/service/ConceptServiceIT.java
+++ b/core/src/test/java/org/gbif/vocabulary/service/ConceptServiceIT.java
@@ -25,7 +25,7 @@
 import org.gbif.vocabulary.model.UserRoles;
 import org.gbif.vocabulary.model.Vocabulary;
 import org.gbif.vocabulary.model.search.ConceptSearchParams;
-import org.gbif.vocabulary.model.search.KeyNameResult;
+import org.gbif.vocabulary.model.search.SuggestResult;
 import org.gbif.vocabulary.persistence.mappers.VocabularyMapper;
 
 import java.sql.Connection;
@@ -883,63 +883,81 @@ public void suggestTest() {
         key3,
         Label.builder().language(LanguageRegion.SPANISH).value("Label3").createdBy("test").build());
 
-    List<KeyNameResult> results =
-        conceptService.suggest("suggest", c1.getVocabularyKey(), null, null);
+    List<SuggestResult> results =
+        conceptService.suggest("suggest", c1.getVocabularyKey(), null, null, null);
     assertEquals(3, results.size());
 
-    results = conceptService.suggest("suggest222", c1.getVocabularyKey(), null, null);
+    results = conceptService.suggest("suggest222", c1.getVocabularyKey(), null, null, null);
     assertEquals(1, results.size());
-    KeyNameResult result = results.get(0);
+    SuggestResult result = results.get(0);
     assertEquals(1, result.getParents().size());
-    KeyNameResult.Parent parent = result.getParents().get(0);
-    assertEquals(2, parent.getLabels().size());
+    SuggestResult.Parent parent = result.getParents().get(0);
 
     results =
-        conceptService.suggest("suggest222", c1.getVocabularyKey(), LanguageRegion.SPANISH, null);
+        conceptService.suggest(
+            "suggest222", c1.getVocabularyKey(), LanguageRegion.SPANISH, null, null);
     assertEquals(1, results.size());
-    result = results.get(0);
-    assertEquals(0, result.getLabels().size());
     assertEquals(1, result.getParents().size());
-    parent = result.getParents().get(0);
-    assertEquals(1, parent.getLabels().size());
-    assertEquals(LanguageRegion.SPANISH, parent.getLabels().get(0).getLanguage());
 
     results =
         conceptService.suggest(
-            "suggest222", c1.getVocabularyKey(), LanguageRegion.SPANISH, LanguageRegion.ENGLISH);
-    assertEquals(1, results.size());
-    result = results.get(0);
-    assertEquals(1, result.getLabels().size());
-    assertEquals(LanguageRegion.ENGLISH, result.getLabels().get(0).getLanguage());
-    assertEquals(1, result.getParents().size());
-    parent = result.getParents().get(0);
-    assertEquals(1, parent.getLabels().size());
-    assertEquals(LanguageRegion.SPANISH, parent.getLabels().get(0).getLanguage());
+            "suggest222",
+            c1.getVocabularyKey(),
+            LanguageRegion.SPANISH,
+            LanguageRegion.ENGLISH,
+            null);
+    assertEquals(0, results.size());
 
-    results = conceptService.suggest("suggest333", c1.getVocabularyKey(), null, null);
+    results =
+        conceptService.suggest(
+            "suggest", c1.getVocabularyKey(), LanguageRegion.FRENCH, LanguageRegion.ENGLISH, null);
     assertEquals(1, results.size());
-    result = results.get(0);
-    assertEquals(2, result.getParents().size());
-    assertEquals(1, result.getLabels().size());
+    assertEquals(c3.getName(), results.get(0).getName());
+    assertEquals(2, results.get(0).getParents().size());
+    assertTrue(
+        results.get(0).getParents().stream()
+            .allMatch(p -> p.getLabelLanguage() == LanguageRegion.ENGLISH));
 
     results =
-        conceptService.suggest("suggest333", c1.getVocabularyKey(), LanguageRegion.SPANISH, null);
-    assertEquals(1, results.size());
-    result = results.get(0);
-    assertEquals(1, result.getLabels().size());
-    assertEquals(LanguageRegion.SPANISH, result.getLabels().get(0).getLanguage());
-    assertEquals(2, result.getParents().size());
+        conceptService.suggest(
+            "label", c1.getVocabularyKey(), LanguageRegion.SPANISH, LanguageRegion.ENGLISH, null);
+    assertEquals(3, results.size());
+    results.forEach(
+        r -> {
+          if (r.getName().equals(c2.getName())) {
+            assertEquals(LanguageRegion.ENGLISH, r.getLabelLanguage());
+          } else {
+            assertEquals(LanguageRegion.SPANISH, r.getLabelLanguage());
+          }
+        });
+
+    results =
+        conceptService.suggest("label", c1.getVocabularyKey(), LanguageRegion.SPANISH, null, null);
+    assertEquals(2, results.size());
+    assertTrue(results.stream().allMatch(r -> r.getLabelLanguage() == LanguageRegion.SPANISH));
+
+    results =
+        conceptService.suggest(
+            "label", c1.getVocabularyKey(), LanguageRegion.FRENCH, LanguageRegion.ENGLISH, null);
+    assertEquals(2, results.size());
+    assertTrue(results.stream().allMatch(r -> r.getLabelLanguage() == LanguageRegion.ENGLISH));
 
     results =
         conceptService.suggest(
-            "suggest333", c1.getVocabularyKey(), LanguageRegion.SPANISH, LanguageRegion.ENGLISH);
+            "label3", c1.getVocabularyKey(), LanguageRegion.SPANISH, LanguageRegion.ENGLISH, null);
     assertEquals(1, results.size());
-    result = results.get(0);
-    assertEquals(1, result.getLabels().size());
-    assertEquals(LanguageRegion.SPANISH, result.getLabels().get(0).getLanguage());
-    assertEquals(2, result.getParents().size());
-    assertEquals(key2, result.getParents().get(0).getKey());
-    assertEquals(key1, result.getParents().get(1).getKey());
+    assertEquals(2, results.get(0).getParents().size());
+    results
+        .get(0)
+        .getParents()
+        .forEach(
+            p -> {
+              if (p.getName().equals(c1.getName())) {
+                assertEquals(LanguageRegion.SPANISH, p.getLabelLanguage());
+              } else {
+                assertEquals(LanguageRegion.ENGLISH, p.getLabelLanguage());
+              }
+            });
   }
 
   static class ContexInitializer
diff --git a/core/src/test/java/org/gbif/vocabulary/service/VocabularyServiceIT.java b/core/src/test/java/org/gbif/vocabulary/service/VocabularyServiceIT.java
index 8bdbc913..709feb8e 100644
--- a/core/src/test/java/org/gbif/vocabulary/service/VocabularyServiceIT.java
+++ b/core/src/test/java/org/gbif/vocabulary/service/VocabularyServiceIT.java
@@ -19,6 +19,7 @@
 import org.gbif.vocabulary.model.LanguageRegion;
 import org.gbif.vocabulary.model.UserRoles;
 import org.gbif.vocabulary.model.Vocabulary;
+import org.gbif.vocabulary.model.search.SuggestResult;
 import org.gbif.vocabulary.model.search.VocabularySearchParams;
 
 import java.sql.Connection;
@@ -316,6 +317,70 @@ public void labelsTest() {
     assertEquals(labelKey2, labelList.get(0).getKey());
   }
 
+  @Test
+  public void suggestTest() {
+    // create entities for the test
+    Vocabulary v1 = createBasicVocabulary();
+    v1.setName("Suggest111");
+
+    vocabularyService.create(v1);
+
+    vocabularyService.addLabel(
+        v1.getKey(),
+        Label.builder()
+            .language(LanguageRegion.SPANISH)
+            .value("labelspanish")
+            .createdBy("test")
+            .build());
+
+    vocabularyService.addLabel(
+        v1.getKey(),
+        Label.builder()
+            .language(LanguageRegion.ENGLISH)
+            .value("labelenglish")
+            .createdBy("test")
+            .build());
+
+    Vocabulary v2 = createBasicVocabulary();
+    v2.setName("Suggest222");
+    vocabularyService.create(v2);
+    assertNotNull(v2.getKey());
+
+    vocabularyService.addLabel(
+        v2.getKey(),
+        Label.builder().language(LanguageRegion.ENGLISH).value("Label").createdBy("test").build());
+
+    List<SuggestResult> result = vocabularyService.suggest("suggest1", null, null, null);
+    assertEquals("Suggest111", result.get(0).getName());
+    assertEquals(v1.getName(), result.get(0).getName());
+
+    // assert expected number of results
+    assertEquals(2, vocabularyService.suggest("su", null, null, null).size());
+    assertEquals(2, vocabularyService.suggest("gge", null, null, null).size());
+    assertEquals(1, vocabularyService.suggest("22", null, null, null).size());
+    assertEquals(0, vocabularyService.suggest("zz", null, null, null).size());
+    assertEquals(2, vocabularyService.suggest(null, null, null, null).size());
+    assertEquals(2, vocabularyService.suggest("label", null, null, null).size());
+    assertEquals(1, vocabularyService.suggest("labeleng", null, null, null).size());
+    assertEquals(
+        0, vocabularyService.suggest("labeleng", LanguageRegion.SPANISH, null, null).size());
+    assertEquals(1, vocabularyService.suggest("label", LanguageRegion.SPANISH, null, null).size());
+    assertEquals(
+        1, vocabularyService.suggest("labeleng", LanguageRegion.ENGLISH, null, null).size());
+
+    result =
+        vocabularyService.suggest("label", LanguageRegion.SPANISH, LanguageRegion.ENGLISH, null);
+    assertEquals(2, result.size());
+    result.forEach(
+        dto -> {
+          if (dto.getName().equals(v2.getName())) {
+            assertEquals(LanguageRegion.ENGLISH, dto.getLabelLanguage());
+          } else {
+            assertEquals(LanguageRegion.SPANISH, dto.getLabelLanguage());
+          }
+        });
+  }
+
   static class ContexInitializer
       implements ApplicationContextInitializer<ConfigurableApplicationContext> {
     public void initialize(ConfigurableApplicationContext configurableApplicationContext) {
diff --git a/model/src/main/java/org/gbif/vocabulary/model/search/KeyNameResult.java b/model/src/main/java/org/gbif/vocabulary/model/search/KeyNameResult.java
index 8a215676..e2fbaa52 100644
--- a/model/src/main/java/org/gbif/vocabulary/model/search/KeyNameResult.java
+++ b/model/src/main/java/org/gbif/vocabulary/model/search/KeyNameResult.java
@@ -13,11 +13,6 @@
  */
 package org.gbif.vocabulary.model.search;
 
-import org.gbif.vocabulary.model.Label;
-
-import java.util.ArrayList;
-import java.util.List;
-
 import lombok.Data;
 
 /**
@@ -28,14 +23,4 @@
 public class KeyNameResult {
   private long key;
   private String name;
-  private List<Label> labels = new ArrayList<>();
-  private List<Parent> parents = new ArrayList<>();
-
-  @Data
-  public static class Parent {
-    private long key;
-    private String name;
-    private int depth;
-    private List<Label> labels = new ArrayList<>();
-  }
 }
diff --git a/model/src/main/java/org/gbif/vocabulary/model/search/SuggestResult.java b/model/src/main/java/org/gbif/vocabulary/model/search/SuggestResult.java
new file mode 100644
index 00000000..ee2f8659
--- /dev/null
+++ b/model/src/main/java/org/gbif/vocabulary/model/search/SuggestResult.java
@@ -0,0 +1,23 @@
+package org.gbif.vocabulary.model.search;
+
+import org.gbif.vocabulary.model.LanguageRegion;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import lombok.Data;
+
+@Data
+public class SuggestResult {
+  private String name;
+  private String label;
+  private LanguageRegion labelLanguage;
+  private List<Parent> parents = new ArrayList<>();
+
+  @Data
+  public static class Parent {
+    private String name;
+    private String label;
+    private LanguageRegion labelLanguage;
+  }
+}
diff --git a/model/src/test/java/org/gbif/vocabulary/model/search/KeyNameResultTest.java b/model/src/test/java/org/gbif/vocabulary/model/search/KeyNameResultTest.java
index ced11de3..ce2b164b 100644
--- a/model/src/test/java/org/gbif/vocabulary/model/search/KeyNameResultTest.java
+++ b/model/src/test/java/org/gbif/vocabulary/model/search/KeyNameResultTest.java
@@ -23,14 +23,12 @@ public class KeyNameResultTest {
   public void equalityTest() {
     KeyNameResult knr1 = new KeyNameResult();
     knr1.setName("a");
-    knr1.setKey(1);
 
     KeyNameResult knr2 = new KeyNameResult();
     knr2.setName(knr1.getName());
 
     Assertions.assertNotEquals(knr1, knr2);
 
-    knr1.setKey(knr2.getKey());
     Assertions.assertEquals(knr1, knr2);
   }
 }
diff --git a/vocabulary-rest-ws-client/src/main/java/org/gbif/vocabulary/client/ConceptClient.java b/vocabulary-rest-ws-client/src/main/java/org/gbif/vocabulary/client/ConceptClient.java
index 44206ea4..1f580b69 100644
--- a/vocabulary-rest-ws-client/src/main/java/org/gbif/vocabulary/client/ConceptClient.java
+++ b/vocabulary-rest-ws-client/src/main/java/org/gbif/vocabulary/client/ConceptClient.java
@@ -311,5 +311,6 @@ class SuggestParams {
     LanguageRegion locale;
     LanguageRegion fallbackLocale;
     String q;
+    Integer limit;
   }
 }
diff --git a/vocabulary-rest-ws-client/src/main/java/org/gbif/vocabulary/client/VocabularyClient.java b/vocabulary-rest-ws-client/src/main/java/org/gbif/vocabulary/client/VocabularyClient.java
index 217e2e0a..07c6630d 100644
--- a/vocabulary-rest-ws-client/src/main/java/org/gbif/vocabulary/client/VocabularyClient.java
+++ b/vocabulary-rest-ws-client/src/main/java/org/gbif/vocabulary/client/VocabularyClient.java
@@ -66,7 +66,7 @@ default Vocabulary update(Vocabulary vocabulary) {
   }
 
   @GetMapping(value = "suggest", produces = MediaType.APPLICATION_JSON_VALUE)
-  List<KeyNameResult> suggest(@RequestParam("q") String query);
+  List<KeyNameResult> suggest(@SpringQueryMap SuggestParams suggestParams);
 
   @PutMapping(
       value = "{name}/deprecate",
@@ -172,4 +172,12 @@ default List<Label> listLabels(String vocabularyName, List<LanguageRegion> langu
   class ListParams {
     List<LanguageRegion> lang;
   }
+
+  @AllArgsConstructor(staticName = "of")
+  class SuggestParams {
+    LanguageRegion locale;
+    LanguageRegion fallbackLocale;
+    String q;
+    Integer limit;
+  }
 }
diff --git a/vocabulary-rest-ws/src/main/java/org/gbif/vocabulary/restws/resources/ConceptResource.java b/vocabulary-rest-ws/src/main/java/org/gbif/vocabulary/restws/resources/ConceptResource.java
index 69f7c280..2d41a3da 100644
--- a/vocabulary-rest-ws/src/main/java/org/gbif/vocabulary/restws/resources/ConceptResource.java
+++ b/vocabulary-rest-ws/src/main/java/org/gbif/vocabulary/restws/resources/ConceptResource.java
@@ -32,7 +32,7 @@
 import org.gbif.vocabulary.model.exception.EntityNotFoundException.EntityType;
 import org.gbif.vocabulary.model.search.ChildrenResult;
 import org.gbif.vocabulary.model.search.ConceptSearchParams;
-import org.gbif.vocabulary.model.search.KeyNameResult;
+import org.gbif.vocabulary.model.search.SuggestResult;
 import org.gbif.vocabulary.restws.config.WsConfig;
 import org.gbif.vocabulary.restws.documentation.Docs;
 import org.gbif.vocabulary.service.ConceptService;
@@ -367,13 +367,17 @@ public ConceptView update(
   @Docs.DefaultSearchResponses
   @Docs.VocabularyNameInConceptPathParameter
   @GetMapping("suggest")
-  public List<KeyNameResult> suggest(
+  public List<SuggestResult> suggest(
       @PathVariable("vocabularyName") String vocabularyName,
       @RequestParam(value = "q", required = false) String query,
       LanguageRegion locale,
-      LanguageRegion fallbackLocale) {
+      LanguageRegion fallbackLocale,
+      @RequestParam(value = "limit", required = false) Integer limit) {
+    if (fallbackLocale != null && locale == null) {
+      throw new IllegalArgumentException("Locale is required if the fallback locale is set");
+    }
     return conceptService.suggest(
-        query, getVocabularyWithCheck(vocabularyName).getKey(), locale, fallbackLocale);
+        query, getVocabularyWithCheck(vocabularyName).getKey(), locale, fallbackLocale, limit);
   }
 
   @Operation(
@@ -923,17 +927,19 @@ public ConceptView getFromLatestRelease(
   @Docs.DefaultSearchResponses
   @Docs.VocabularyNameInConceptPathParameter
   @GetMapping(LATEST_RELEASE_PATH + "/suggest")
-  public List<KeyNameResult> suggestLatestRelease(
+  public List<SuggestResult> suggestLatestRelease(
       @PathVariable("vocabularyName") String vocabularyName,
       @RequestParam(value = "q", required = false) String query,
       LanguageRegion locale,
-      LanguageRegion fallbackLocale) {
+      LanguageRegion fallbackLocale,
+      @RequestParam(value = "limit", required = false) Integer limit) {
     return conceptService.suggestLatestRelease(
         query,
         getVocabularyWithCheck(vocabularyName).getKey(),
         locale,
         fallbackLocale,
-        vocabularyName);
+        vocabularyName,
+        limit);
   }
 
   @Operation(
diff --git a/vocabulary-rest-ws/src/main/java/org/gbif/vocabulary/restws/resources/VocabularyResource.java b/vocabulary-rest-ws/src/main/java/org/gbif/vocabulary/restws/resources/VocabularyResource.java
index ebc7b5c2..a032a023 100644
--- a/vocabulary-rest-ws/src/main/java/org/gbif/vocabulary/restws/resources/VocabularyResource.java
+++ b/vocabulary-rest-ws/src/main/java/org/gbif/vocabulary/restws/resources/VocabularyResource.java
@@ -29,7 +29,7 @@
 import org.gbif.vocabulary.model.VocabularyRelease;
 import org.gbif.vocabulary.model.exception.EntityNotFoundException;
 import org.gbif.vocabulary.model.export.ExportParams;
-import org.gbif.vocabulary.model.search.KeyNameResult;
+import org.gbif.vocabulary.model.search.SuggestResult;
 import org.gbif.vocabulary.model.search.VocabularySearchParams;
 import org.gbif.vocabulary.restws.config.ExportConfig;
 import org.gbif.vocabulary.restws.documentation.Docs;
@@ -260,9 +260,12 @@ public Vocabulary update(
   @Docs.LocaleParameter
   @Docs.DefaultSearchResponses
   @GetMapping("suggest")
-  public List<KeyNameResult> suggest(
-      @RequestParam(value = "q", required = false) String query, LanguageRegion locale) {
-    return vocabularyService.suggest(query, locale);
+  public List<SuggestResult> suggest(
+      @RequestParam(value = "q", required = false) String query,
+      LanguageRegion locale,
+      LanguageRegion fallbackLocale,
+      @RequestParam(value = "limit", required = false) Integer limit) {
+    return vocabularyService.suggest(query, locale, fallbackLocale, limit);
   }
 
   @Operation(
diff --git a/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/ConceptResourceIT.java b/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/ConceptResourceIT.java
index f1667421..f3f8f0a5 100644
--- a/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/ConceptResourceIT.java
+++ b/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/ConceptResourceIT.java
@@ -476,7 +476,8 @@ public void releaseViewTest() {
         1,
         conceptClient
             .suggestLatestRelease(
-                defaultVocabularyName, ConceptClient.SuggestParams.of(null, null, c1.getName()))
+                defaultVocabularyName,
+                ConceptClient.SuggestParams.of(null, null, c1.getName(), null))
             .size());
 
     assertEquals(
diff --git a/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/mock/BaseResourceTest.java b/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/mock/BaseResourceTest.java
index 58c6d467..841d70b5 100644
--- a/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/mock/BaseResourceTest.java
+++ b/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/mock/BaseResourceTest.java
@@ -22,6 +22,8 @@
 import java.util.Arrays;
 import java.util.List;
 
+import org.gbif.vocabulary.model.search.SuggestResult;
+
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -127,7 +129,7 @@ Vocabulary createVocabulary(String name) {
     return vocabulary;
   }
 
-  void suggestTest(List<KeyNameResult> suggestions) throws Exception {
+  void suggestTest(List<SuggestResult> suggestions) throws Exception {
     MvcResult mvcResult =
         mockMvc
             .perform(get(getBasePath() + "/suggest?q=foo"))
@@ -141,14 +143,12 @@ void suggestTest(List<KeyNameResult> suggestions) throws Exception {
     assertEquals(suggestions.size(), resultList.size());
   }
 
-  List<KeyNameResult> createSuggestions() {
-    KeyNameResult keyNameResult1 = new KeyNameResult();
-    keyNameResult1.setKey(1);
-    keyNameResult1.setName("n1");
-    KeyNameResult keyNameResult2 = new KeyNameResult();
-    keyNameResult2.setKey(2);
-    keyNameResult2.setName("n2");
-    return ImmutableList.of(keyNameResult1, keyNameResult2);
+  List<SuggestResult> createSuggestions() {
+    SuggestResult result1 = new SuggestResult();
+    result1.setName("n1");
+    SuggestResult result2 = new SuggestResult();
+    result2.setName("n2");
+    return ImmutableList.of(result1, result2);
   }
 
   abstract String getBasePath();
diff --git a/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/mock/ConceptResourceTest.java b/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/mock/ConceptResourceTest.java
index 72e89b86..26a0965e 100644
--- a/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/mock/ConceptResourceTest.java
+++ b/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/mock/ConceptResourceTest.java
@@ -22,7 +22,7 @@
 import org.gbif.vocabulary.model.UserRoles;
 import org.gbif.vocabulary.model.Vocabulary;
 import org.gbif.vocabulary.model.search.ConceptSearchParams;
-import org.gbif.vocabulary.model.search.KeyNameResult;
+import org.gbif.vocabulary.model.search.SuggestResult;
 import org.gbif.vocabulary.restws.resources.ConceptResource;
 import org.gbif.vocabulary.service.ConceptService;
 import org.gbif.vocabulary.service.VocabularyService;
@@ -199,8 +199,9 @@ public void updateConceptWithWrongConceptName() throws Exception {
   @Test
   public void suggestTest() throws Exception {
     mockVocabulary();
-    List<KeyNameResult> suggestions = createSuggestions();
-    when(conceptService.suggest(anyString(), anyLong(), any(), any())).thenReturn(suggestions);
+    List<SuggestResult> suggestions = createSuggestions();
+    when(conceptService.suggest(anyString(), anyLong(), any(), any(), any()))
+        .thenReturn(suggestions);
     suggestTest(suggestions);
   }
 
diff --git a/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/mock/VocabularyResourceTest.java b/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/mock/VocabularyResourceTest.java
index 06886448..e14f6417 100644
--- a/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/mock/VocabularyResourceTest.java
+++ b/vocabulary-rest-ws/src/test/java/org/gbif/vocabulary/restws/resources/mock/VocabularyResourceTest.java
@@ -21,7 +21,7 @@
 import org.gbif.vocabulary.model.UserRoles;
 import org.gbif.vocabulary.model.Vocabulary;
 import org.gbif.vocabulary.model.VocabularyRelease;
-import org.gbif.vocabulary.model.search.KeyNameResult;
+import org.gbif.vocabulary.model.search.SuggestResult;
 import org.gbif.vocabulary.model.search.VocabularySearchParams;
 import org.gbif.vocabulary.restws.resources.VocabularyResource;
 import org.gbif.vocabulary.service.ExportService;
@@ -155,8 +155,8 @@ public void updateWrongNameTest() throws Exception {
 
   @Test
   public void suggestTest() throws Exception {
-    List<KeyNameResult> suggestions = createSuggestions();
-    when(vocabularyService.suggest(anyString(), any())).thenReturn(suggestions);
+    List<SuggestResult> suggestions = createSuggestions();
+    when(vocabularyService.suggest(anyString(), any(), any(), any())).thenReturn(suggestions);
     suggestTest(suggestions);
   }