Feature #8439 - Syntax rules for ambiguous name resolution.

Author: asfernandes

doc/sql.extensions/README.name_resolution.md

@@ -0,0 +1,68 @@
+# Name resolution (FB 6.0)
+
+With the introduction of schemas in Firebird 6.0, the syntax `<name>.<name>` - used for tables, views, procedures,
+and functions (both standalone and packaged) - introduces ambiguity when resolving object names using the schema
+search path. The ambiguity arises between:
+
+- `<schema>.<object>` (a schema and its object)
+- `<package>.<object>` (a package and its object)
+
+This document focuses on name resolution rules for tables, views, procedures, and functions within queries and
+code blocks.
+
+## Scope specifier (`%`)
+
+To resolve these ambiguities, Firebird introduces a **scope specifier**, represented by the `%` symbol. This
+allows unambiguous referencing of objects.
+
+### Syntax
+
+```sql
+<name> % { SCHEMA | PACKAGE } . <name>
+```
+
+### Examples
+
+```sql
+select *
+    from plg$profiler%schema.plg$prof_sessions;
+
+execute procedure rdb$profiler%package.pause_session;
+
+call rdb$profiler%package.pause_session();
+
+select rdb$time_zone_util%package.database_version()
+    from system%schema.rdb$database;
+
+select *
+    from rdb$time_zone_util%package.transitions('America/Sao_Paulo', timestamp '2017-01-01', timestamp '2019-01-01');
+```
+
+## Detailed name resolution rules
+
+Firebird resolves object names following a structured sequence of rules. Once an object is located, the resolution
+process halts, ensuring no ambiguity errors occur.
+
+- **`name1.name2.name3`**
+  1. Look for routine `name3` inside package `name2`, inside schema `name1`.
+
+- **`name1%schema.name2`**
+  1. Look for object `name2` inside schema `name1`.
+
+- **`name1%package.name2`**
+  1. Look for object `name2` inside a package `name1` using the schema search path.
+
+- **`name1.name2`**
+  1. If inside a package named `name1`, look for routine `name2` in the same package.
+  2. Look in schema `name1` for object `name2`.
+  3. Look for object `name2` inside a package `name1` using the schema search path.
+
+- **`name`**
+  1. Look for subroutine `name`.
+  2. If inside a package, look for routine `name` in the same package.
+  3. Look for object `name` using the schema search path.
+
+> **_Note:_** Object resolution also depends on the context in which they are used. For example, in
+`select * from name1.name2`, `name2` could be a table, view, or procedure. However, in
+`execute procedure name1.name2`, `name2` must be a procedure. This distinction means that an `execute procedure`
+command versus a `select` command can resolve to different objects.

doc/sql.extensions/README.schemas.md

@@ -162,12 +162,7 @@ end;
 ### Resolving between `PACKAGE.OBJECT` and `SCHEMA.OBJECT`
 
 The syntax `<name>.<name>` introduces ambiguity between `<package>.<object>` and `<schema>.<object>` when referring to 
-procedures and functions.
-
-In such cases, the system first searches for a package name using the search path. If a matching package is found, the 
-name is resolved as `<package>.<object>` within the schema where the package resides.
-
-If no package is found, the name is interpreted as a fully qualified `<schema>.<object>` instead.
+procedures and functions. See [name resolution](README.name_resolution.md) for details.
 
 ## Permissions
 

src/auth/SecureRemotePassword/manage/SrpManagement.cpp

@@ -609,7 +609,7 @@ class SrpManagement final : public Firebird::StdPlugin<Firebird::IManagementImpl
 						"	WHERE RDB$RELATION_NAME = 'RDB$ADMIN' AND RDB$PRIVILEGE = 'M' GROUP BY RDB$USER) "
 						"SELECT PLG$USER_NAME, PLG$FIRST, PLG$MIDDLE, PLG$LAST, PLG$COMMENT, PLG$ATTRIBUTES, "
 						"	CASE WHEN RDB$USER IS NULL THEN FALSE ELSE TRUE END, PLG$ACTIVE "
-						"FROM PLG$SRP.PLG$SRP_VIEW LEFT JOIN ADMINS "
+						"FROM PLG$SRP%SCHEMA.PLG$SRP_VIEW LEFT JOIN ADMINS "
 						"	ON PLG$SRP_VIEW.PLG$USER_NAME = ADMINS.RDB$USER ";
 					if (user->userName()->entered())
 					{

src/auth/SecureRemotePassword/server/SrpServer.cpp

@@ -196,7 +196,7 @@ class SecurityDatabase : public VSecDb
 			HANDSHAKE_DEBUG(fprintf(stderr, "Srv: SRP1: started transaction\n"));
 
 			const char* sql =
-				"SELECT PLG$VERIFIER, PLG$SALT FROM PLG$SRP.PLG$SRP WHERE PLG$USER_NAME = ? AND PLG$ACTIVE";
+				"SELECT PLG$VERIFIER, PLG$SALT FROM PLG$SRP%SCHEMA.PLG$SRP WHERE PLG$USER_NAME = ? AND PLG$ACTIVE";
 			stmt = att->prepare(&status, tra, 0, sql, 3, IStatement::PREPARE_PREFETCH_METADATA);
 			if (status->getState() & IStatus::STATE_ERRORS)
 			{

src/common/classes/QualifiedMetaString.h

@@ -52,22 +52,25 @@ class BaseQualifiedName
 	BaseQualifiedName(MemoryPool& p, const BaseQualifiedName& src)
 		: object(p, src.object),
 		  schema(p, src.schema),
-		  package(p, src.package)
+		  package(p, src.package),
+		  unambiguous(src.isUnambiguous())
 	{
 	}
 
 	BaseQualifiedName(const BaseQualifiedName& src)
 		: object(src.object),
 		  schema(src.schema),
-		  package(src.package)
+		  package(src.package),
+		  unambiguous(src.isUnambiguous())
 	{
 	}
 
 	template <typename TT>
 	BaseQualifiedName(const BaseQualifiedName<TT>& src)
 		: object(src.object),
 		  schema(src.schema),
-		  package(src.package)
+		  package(src.package),
+		  unambiguous(src.isUnambiguous())
 	{
 	}
 
@@ -222,6 +225,16 @@ class BaseQualifiedName
 	}
 
 public:
+	bool isUnambiguous() const
+	{
+		return unambiguous;
+	}
+
+	void setUnambiguous(bool value)
+	{
+		unambiguous = value;
+	}
+
 	BaseQualifiedName getSchemaAndPackage() const
 	{
 		return BaseQualifiedName(package, schema);
@@ -263,6 +276,9 @@ class BaseQualifiedName
 	T object;
 	T schema;
 	T package;
+
+private:
+	bool unambiguous = false;
 };
 
 using QualifiedMetaString = Firebird::BaseQualifiedName<MetaString>;

src/dsql/DsqlCompilerScratch.cpp

@@ -30,7 +30,9 @@
 #include "../dsql/errd_proto.h"
 #include "../dsql/gen_proto.h"
 #include "../dsql/make_proto.h"
+#include "../dsql/metd_proto.h"
 #include "../dsql/pass1_proto.h"
+#include <unordered_set>
 
 using namespace Firebird;
 using namespace Jrd;
@@ -72,7 +74,7 @@ void DsqlCompilerScratch::qualifyNewName(QualifiedName& name) const
 	}
 }
 
-void DsqlCompilerScratch::qualifyExistingName(QualifiedName& name, ObjectType objectType)
+void DsqlCompilerScratch::qualifyExistingName(QualifiedName& name, std::initializer_list<ObjectType> objectTypes)
 {
 	if (!(name.schema.isEmpty() && name.object.hasData()))
 		return;
@@ -96,10 +98,123 @@ void DsqlCompilerScratch::qualifyExistingName(QualifiedName& name, ObjectType ob
 			}
 		}
 
-		attachment->qualifyExistingName(tdbb, name, objectType, cachedDdlSchemaSearchPath);
+		attachment->qualifyExistingName(tdbb, name, objectTypes, cachedDdlSchemaSearchPath);
 	}
 	else
-		attachment->qualifyExistingName(tdbb, name, objectType);
+		attachment->qualifyExistingName(tdbb, name, objectTypes);
+}
+
+
+std::variant<std::monostate, dsql_prc*, dsql_rel*, dsql_udf*> DsqlCompilerScratch::resolveRoutineOrRelation(
+	QualifiedName& name, std::initializer_list<ObjectType> objectTypes)
+{
+	const std::unordered_set<ObjectType> objectTypesSet(objectTypes);
+	const bool searchProcedures = objectTypesSet.find(obj_procedure) != objectTypesSet.end();
+	const bool searchRelations = objectTypesSet.find(obj_relation) != objectTypesSet.end();
+	const bool searchFunctions = objectTypesSet.find(obj_udf) != objectTypesSet.end();
+	fb_assert((searchProcedures || searchRelations) != searchFunctions);
+
+	std::variant<std::monostate, dsql_prc*, dsql_rel*, dsql_udf*> object;
+
+	const auto notFound = [&]()
+	{
+		return std::holds_alternative<std::monostate>(object);
+	};
+
+	const auto setObject = [&](const auto value)
+	{
+		if (value)
+			object = value;
+	};
+
+	// search subroutine: name
+	if (name.schema.isEmpty() &&
+		name.package.isEmpty())
+	{
+		if (searchProcedures)
+		{
+			if (const auto subProcedure = getSubProcedure(name.object))
+				setObject(subProcedure->dsqlProcedure);
+		}
+
+		if (searchFunctions)
+		{
+			if (const auto subFunction = getSubFunction(name.object))
+				setObject(subFunction->dsqlFunction);
+		}
+	}
+
+	// search packaged routine in the same package: name, same_package.name
+	if (notFound() &&
+		package.object.hasData() &&
+		name.package.isEmpty() &&
+		(name.schema.isEmpty() ||
+			(!name.isUnambiguous() && name.schema == package.object)))
+	{
+		const QualifiedName routineName(name.object, package.schema, package.object);
+
+		if (searchProcedures)
+			setObject(METD_get_procedure(getTransaction(), this, routineName));
+
+		if (searchFunctions)
+			setObject(METD_get_function(getTransaction(), this, routineName));
+	}
+
+	// search standalone routine or relation: name, name1%schema.name2, name1.name2
+	if (notFound() &&
+		name.package.isEmpty())
+	{
+		auto qualifiedName = name;
+		qualifyExistingName(qualifiedName, objectTypes);
+
+		if (searchProcedures)
+			setObject(METD_get_procedure(getTransaction(), this, qualifiedName));
+
+		if (searchRelations)
+			setObject(METD_get_relation(getTransaction(), this, qualifiedName));
+
+		if (searchFunctions)
+			setObject(METD_get_function(getTransaction(), this, qualifiedName));
+	}
+
+	// search packaged routine: name1%package.name2, name1.name2.name3
+	if (notFound() &&
+		name.package.hasData())
+	{
+		auto qualifiedName = name;
+		qualifyExistingName(qualifiedName, objectTypes);
+
+		if (searchProcedures)
+			setObject(METD_get_procedure(getTransaction(), this, qualifiedName));
+
+		if (searchFunctions)
+			setObject(METD_get_function(getTransaction(), this, qualifiedName));
+	}
+
+	// search packaged routine: name1.name2
+	if (notFound() &&
+		!name.isUnambiguous() &&
+		name.schema.hasData() &&
+		name.package.isEmpty())
+	{
+		QualifiedName qualifiedName(name.object, {}, name.schema);
+		qualifyExistingName(qualifiedName, objectTypes);
+
+		if (searchProcedures)
+			setObject(METD_get_procedure(getTransaction(), this, qualifiedName));
+
+		if (searchFunctions)
+			setObject(METD_get_function(getTransaction(), this, qualifiedName));
+	}
+
+	if (const auto procedure = std::get_if<dsql_prc*>(&object))
+		name = (*procedure)->prc_name;
+	else if (const auto relation = std::get_if<dsql_rel*>(&object))
+		name = (*relation)->rel_name;
+	else if (const auto function = std::get_if<dsql_udf*>(&object))
+		name = (*function)->udf_name;
+
+	return object;
 }
 
 

src/dsql/DsqlCompilerScratch.h

@@ -30,7 +30,9 @@
 #include "../jrd/MetaName.h"
 #include "../common/classes/stack.h"
 #include "../common/classes/alloc.h"
+#include <initializer_list>
 #include <optional>
+#include <variant>
 
 namespace Jrd
 {
@@ -153,7 +155,15 @@ class DsqlCompilerScratch : public BlrDebugWriter
 	}
 
 	void qualifyNewName(QualifiedName& name) const;
-	void qualifyExistingName(QualifiedName& name, ObjectType objectType);
+	void qualifyExistingName(QualifiedName& name, std::initializer_list<ObjectType> objectTypes);
+
+	void qualifyExistingName(QualifiedName& name, ObjectType objectType)
+	{
+		qualifyExistingName(name, {objectType});
+	}
+
+	std::variant<std::monostate, dsql_prc*, dsql_rel*, dsql_udf*> resolveRoutineOrRelation(QualifiedName& name,
+		std::initializer_list<ObjectType> objectTypes);
 
 	void putBlrMarkers(ULONG marks);
 	void putDtype(const TypeClause* field, bool useSubType);

src/dsql/ExprNodes.cpp

@@ -13826,38 +13826,11 @@ dsc* UdfCallNode::execute(thread_db* tdbb, Request* request) const
 
 ValueExprNode* UdfCallNode::dsqlPass(DsqlCompilerScratch* dsqlScratch)
 {
+	const auto resolvedObject = dsqlScratch->resolveRoutineOrRelation(name, {obj_udf});
 	dsql_udf* function = nullptr;
 
-	if (name.package.isEmpty())
-	{
-		if (name.schema.isEmpty())
-		{
-			if (const auto subFunction = dsqlScratch->getSubFunction(name.object))
-				function = subFunction->dsqlFunction;
-			else if (dsqlScratch->package.object.hasData())
-			{
-				const QualifiedName packagedName(name.object, dsqlScratch->package.schema, dsqlScratch->package.object);
-				function = METD_get_function(dsqlScratch->getTransaction(), dsqlScratch, packagedName);
-			}
-
-			if (!function)
-				dsqlScratch->qualifyExistingName(name, obj_udf);
-		}
-		else
-		{
-			QualifiedName packageName(name.schema);
-			dsqlScratch->qualifyExistingName(packageName, obj_package_header);
-
-			if (MET_check_package_exists(JRD_get_thread_data(), packageName))
-			{
-				name.schema = packageName.schema;
-				name.package = packageName.object;
-			}
-		}
-	}
-
-	if (!function)
-		function = METD_get_function(dsqlScratch->getTransaction(), dsqlScratch, name);
+	if (const auto resolvedFunction = std::get_if<dsql_udf*>(&resolvedObject))
+		function = *resolvedFunction;
 
 	if (!function)
 	{
@@ -13874,8 +13847,6 @@ ValueExprNode* UdfCallNode::dsqlPass(DsqlCompilerScratch* dsqlScratch)
 			function->udf_name.getSchemaAndPackage().toQuotedString());
 	}
 
-	name = function->udf_name;
-
 	const auto node = FB_NEW_POOL(dsqlScratch->getPool()) UdfCallNode(dsqlScratch->getPool(), name,
 		doDsqlPass(dsqlScratch, args),
 		dsqlArgNames ?