diff --git a/sql/core/src/main/scala/org/apache/spark/sql/catalog/Catalog.scala b/sql/core/src/main/scala/org/apache/spark/sql/catalog/Catalog.scala
index e75ba094da4f0..29b35229e9753 100644
--- a/sql/core/src/main/scala/org/apache/spark/sql/catalog/Catalog.scala
+++ b/sql/core/src/main/scala/org/apache/spark/sql/catalog/Catalog.scala
@@ -101,6 +101,9 @@ abstract class Catalog {
   /**
    * Returns a list of columns for the given table/view in the specified database.
    *
+   * This API does not support 3 layer namespace since 3.4.0. To use 3 layer namespace,
+   * use listColumns(tableName) instead.
+   *
    * @param dbName is a name that designates a database.
    * @param tableName is an unqualified name that designates a table/view.
    * @since 2.0.0
@@ -133,6 +136,9 @@ abstract class Catalog {
    * Get the table or view with the specified name in the specified database. This throws an
    * AnalysisException when no Table can be found.
    *
+   * This API does not support 3 layer namespace since 3.4.0. To use 3 layer namespace,
+   * use getTable(tableName) instead.
+   *
    * @since 2.1.0
    */
   @throws[AnalysisException]("database or table does not exist")
@@ -154,6 +160,9 @@ abstract class Catalog {
    * Get the function with the specified name. This throws an AnalysisException when the function
    * cannot be found.
    *
+   * This API does not support 3 layer namespace since 3.4.0. To use 3 layer namespace,
+   * use getFunction(functionName) instead.
+   *
    * @param dbName is a name that designates a database.
    * @param functionName is an unqualified name that designates a function in the specified database
    * @since 2.1.0
@@ -182,6 +191,9 @@ abstract class Catalog {
   /**
    * Check if the table or view with the specified name exists in the specified database.
    *
+   * This API does not support 3 layer namespace since 3.4.0. To use 3 layer namespace,
+   * use tableExists(tableName) instead.
+   *
    * @param dbName is a name that designates a database.
    * @param tableName is an unqualified name that designates a table.
    * @since 2.1.0
@@ -202,6 +214,9 @@ abstract class Catalog {
   /**
    * Check if the function with the specified name exists in the specified database.
    *
+   * This API does not support 3 layer namespace since 3.4.0. To use 3 layer namespace,
+   * use functionExists(functionName) instead.
+   *
    * @param dbName is a name that designates a database.
    * @param functionName is an unqualified name that designates a function.
    * @since 2.1.0