Manage permissions for vector APIs with RAM-AnalyticDB(AnalyticDB)-阿里云帮助中心

Use Resource Access Management (RAM) to grant RAM users fine-grained access to the vector APIs of AnalyticDB for PostgreSQL. This lets you control which users can perform specific API operations—whether that's managing namespaces and collections, reading and writing vector data, or using third-party integrations like LlamaIndex and Dify.

Key concepts

RAM users are identities you create under your Alibaba Cloud account. Each RAM user can be assigned a different set of permissions, which is useful when different teams or applications need access to different API operations.

Access policies define what operations are allowed or denied on which resources. RAM supports two types:

System policies: Managed by Alibaba Cloud. You can attach them to users but cannot edit them. For AnalyticDB for PostgreSQL, two system policies are available: AliyunGPDBFullAccess (full management access) and AliyunGPDBReadOnlyAccess (read-only access).
Custom policies: Policies you create, update, and delete. You are responsible for maintaining the versions of these policies. Use custom policies when you need to restrict access to specific API operations or specific instances.

Grant RAM users access to vector APIs

Prerequisites

Before you begin, ensure that you have:

An Alibaba Cloud account with RAM management permissions
An AnalyticDB for PostgreSQL instance

Steps

Create a RAM user.
Create a custom policy. Use the policy examples in this document to define which API operations the user can perform and which instances they can access.
Attach the policy to the RAM user.

Resource field format

In a custom policy, the Resource field specifies which instances the policy applies to. The format is:

acs:gpdb:{region}:{owner_ali_uid}:{resource_name}/{resource_id}

Placeholder	Description
`region`	Region where the instance resides
`owner_ali_uid`	Your Alibaba Cloud account ID
`resource_name`	Resource type: `dbinstance`, `namespace`, `collection`, `document`, `dataapi`, or `secret`
`resource_id`	ID of the specific resource

Use * as a wildcard to match any value.

Note

The examples in this document use an instance ID of gp-test1 and an account ID of 123456. Replace these with your actual values.

Policy examples

The following examples show ready-to-use policies for common scenarios. Each policy grants only the permissions required for that scenario, following the principle of least privilege.

Grant access to all vector APIs

This policy grants access to all vector-related API operations across all instances. The vector APIs cover four resource types: dbinstance, namespace, collection, and document.

The actions fall into two categories:

Management operations: Initialize the vector database; create, delete, and list namespaces, collections, and document collections; manage vector indexes; grant collection access.
Data operations: Upsert, query, update, and delete vector data; upload and manage documents; run text embedding and reranking; interact with knowledge bases.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "gpdb:InitVectorDatabase",
        "gpdb:CreateNamespace",
        "gpdb:DeleteNamespace",
        "gpdb:DescribeNamespace",
        "gpdb:ListNamespaces",
        "gpdb:CreateDocumentCollection",
        "gpdb:ListDocumentCollections",
        "gpdb:DeleteDocumentCollection",
        "gpdb:UpsertChunks",
        "gpdb:UploadDocumentAsync",
        "gpdb:GetUploadDocumentJob",
        "gpdb:CancelUploadDocumentJob",
        "gpdb:QueryContent",
        "gpdb:ListDocuments",
        "gpdb:DescribeDocument",
        "gpdb:DeleteDocument",
        "gpdb:CreateCollection",
        "gpdb:DescribeCollection",
        "gpdb:ListCollections",
        "gpdb:DeleteCollection",
        "gpdb:GrantCollection",
        "gpdb:CancelUpsertCollectionDataJob",
        "gpdb:GetUpsertCollectionDataJob",
        "gpdb:UpsertCollectionData",
        "gpdb:UpsertCollectionDataAsync",
        "gpdb:QueryCollectionData",
        "gpdb:UpdateCollectionDataMetadata",
        "gpdb:DeleteCollectionData",
        "gpdb:CreateVectorIndex",
        "gpdb:DeleteVectorIndex",
        "gpdb:ChatWithKnowledgeBase",
        "gpdb:ChatWithKnowledgeBaseStream",
        "gpdb:QueryKnowledgeBasesContent",
        "gpdb:TextEmbedding",
        "gpdb:Rerank"
      ],
      "Resource": [
        "*"
      ],
      "Condition": {}
    }
  ]
}

Restrict to a specific instance: To limit access to a single instance, replace the Resource field with:

"Resource": [
  "acs:gpdb:*:123456:dbinstance/gp-test1",
  "acs:gpdb:*:123456:namespace/gp-test1",
  "acs:gpdb:*:123456:collection/gp-test1",
  "acs:gpdb:*:123456:document/gp-test1"
]

Grant access for LlamaIndex integration

Use this policy when integrating LlamaIndex with AnalyticDB for PostgreSQL as a vector database.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "gpdb:InitVectorDatabase",
        "gpdb:CreateNamespace",
        "gpdb:DescribeNamespace",
        "gpdb:CreateCollection",
        "gpdb:DescribeCollection",
        "gpdb:DeleteCollection",
        "gpdb:UpsertCollectionData",
        "gpdb:QueryCollectionData",
        "gpdb:DeleteCollectionData"
      ],
      "Resource": [
        "acs:gpdb:*:123456:dbinstance/gp-test1",
        "acs:gpdb:*:123456:namespace/gp-test1",
        "acs:gpdb:*:123456:collection/gp-test1"
      ],
      "Condition": {}
    }
  ]
}

Grant access for the Dify plugin

Use this policy when using the Dify plugin for the retrieval-augmented generation (RAG) service of AnalyticDB for PostgreSQL.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "gpdb:InitVectorDatabase",
        "gpdb:CreateNamespace",
        "gpdb:DeleteNamespace",
        "gpdb:DescribeNamespace",
        "gpdb:ListNamespaces",
        "gpdb:CreateDocumentCollection",
        "gpdb:ListDocumentCollections",
        "gpdb:DeleteDocumentCollection",
        "gpdb:UpsertChunks",
        "gpdb:UploadDocumentAsync",
        "gpdb:GetUploadDocumentJob",
        "gpdb:CancelUploadDocumentJob",
        "gpdb:QueryContent",
        "gpdb:ListDocuments",
        "gpdb:DescribeDocument",
        "gpdb:DeleteDocument",
        "gpdb:CancelUpsertCollectionDataJob",
        "gpdb:GetUpsertCollectionDataJob",
        "gpdb:UpdateCollectionDataMetadata",
        "gpdb:ChatWithKnowledgeBase",
        "gpdb:ChatWithKnowledgeBaseStream",
        "gpdb:QueryKnowledgeBasesContent",
        "gpdb:TextEmbedding",
        "gpdb:Rerank"
      ],
      "Resource": [
        "acs:gpdb:*:123456:dbinstance/gp-test1",
        "acs:gpdb:*:123456:namespace/gp-test1",
        "acs:gpdb:*:123456:collection/gp-test1",
        "acs:gpdb:*:123456:document/gp-test1"
      ],
      "Condition": {}
    }
  ]
}

Grant access for Dify integration

Use this policy when using Dify with AnalyticDB for PostgreSQL as a vector database.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "gpdb:InitVectorDatabase",
        "gpdb:DescribeNamespace",
        "gpdb:CreateNamespace",
        "gpdb:DescribeCollection",
        "gpdb:CreateCollection",
        "gpdb:UpsertCollectionData",
        "gpdb:QueryCollectionData",
        "gpdb:DeleteCollectionData",
        "gpdb:DeleteCollection"
      ],
      "Resource": [
        "acs:gpdb:*:123456:dbinstance/gp-test1",
        "acs:gpdb:*:123456:namespace/gp-test1",
        "acs:gpdb:*:123456:collection/gp-test1"
      ],
      "Condition": {}
    }
  ]
}

Grant access for Data API

The Data API uses two separate permission layers:

`dataapi`: Controls SQL operations such as listing databases and running queries.
`secret`: Controls access to the database credentials used to authenticate those queries.

To use the Data API, a user needs dataapi permissions plus access to a secret (either full secret management permissions, or gpdb:UseSecret on a specific secret).

Important

If you grant dataapi permissions without secret access, the user cannot authenticate and all Data API requests will fail.

The following policy grants full Data API access, including credential management:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "gpdb:ListDatabases",
        "gpdb:ListSchemas",
        "gpdb:ListTables",
        "gpdb:DescribeTable",
        "gpdb:ExecuteStatement"
      ],
      "Resource": [
        "acs:gpdb:*:123456:dataapi/*"
      ],
      "Condition": {}
    },
    {
      "Effect": "Allow",
      "Action": [
        "gpdb:GetSecretValue",
        "gpdb:CreateSecret",
        "gpdb:DeleteSecret",
        "gpdb:ListSecrets"
      ],
      "Resource": [
        "acs:gpdb:*:123456:secret/*"
      ],
      "Condition": {}
    }
  ]
}

Separate credential management from query access: To prevent application developers from retrieving or managing database credentials, split the permissions across two RAM users:

Grant an administrator (RAM user A) full secret management permissions:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "gpdb:GetSecretValue",
        "gpdb:CreateSecret",
        "gpdb:DeleteSecret",
        "gpdb:ListSecrets"
      ],
      "Resource": [
        "acs:gpdb:*:123456:secret/*"
      ],
      "Condition": {}
    }
  ]
}

The administrator calls CreateSecret to create a credential. This returns a SecretARN, for example: acs:gpdb:cn-hangzhou:123456:secret/Foo-C9D56DF3-269D-4C92-9D38-8F647292****.

Grant the application developer (RAM user B) permissions to run Data API queries using only that specific secret—without the ability to retrieve or manage credentials:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "gpdb:ListDatabases",
        "gpdb:ListSchemas",
        "gpdb:ListTables",
        "gpdb:DescribeTable",
        "gpdb:ExecuteStatement"
      ],
      "Resource": [
        "acs:gpdb:*:123456:dataapi/*"
      ],
      "Condition": {}
    },
    {
      "Effect": "Allow",
      "Action": [
        "gpdb:UseSecret"
      ],
      "Resource": [
        "acs:gpdb:*:123456:secret/Foo-C9D56DF3-269D-4C92-9D38-8F647292****"
      ],
      "Condition": {}
    }
  ]
}

Permissions by scenario

The following table shows which API operations each scenario requires. Use it to verify your policy includes all necessary permissions or to compare requirements across scenarios.

Operation	All vector APIs	LlamaIndex	Dify plugin	Dify integration	Data API
`InitVectorDatabase`	Yes	Yes	Yes	Yes
`CreateNamespace`	Yes	Yes	Yes	Yes
`DeleteNamespace`	Yes		Yes
`DescribeNamespace`	Yes	Yes	Yes	Yes
`ListNamespaces`	Yes		Yes
`CreateDocumentCollection`	Yes		Yes
`ListDocumentCollections`	Yes		Yes
`DeleteDocumentCollection`	Yes		Yes
`UpsertChunks`	Yes		Yes
`UploadDocumentAsync`	Yes		Yes
`GetUploadDocumentJob`	Yes		Yes
`CancelUploadDocumentJob`	Yes		Yes
`QueryContent`	Yes		Yes
`ListDocuments`	Yes		Yes
`DescribeDocument`	Yes		Yes
`DeleteDocument`	Yes		Yes
`CreateCollection`	Yes	Yes		Yes
`DescribeCollection`	Yes	Yes		Yes
`ListCollections`	Yes
`DeleteCollection`	Yes	Yes		Yes
`GrantCollection`	Yes
`CancelUpsertCollectionDataJob`	Yes		Yes
`GetUpsertCollectionDataJob`	Yes		Yes
`UpsertCollectionData`	Yes	Yes		Yes
`UpsertCollectionDataAsync`	Yes
`QueryCollectionData`	Yes	Yes		Yes
`UpdateCollectionDataMetadata`	Yes		Yes
`DeleteCollectionData`	Yes	Yes		Yes
`CreateVectorIndex`	Yes
`DeleteVectorIndex`	Yes
`ChatWithKnowledgeBase`	Yes		Yes
`ChatWithKnowledgeBaseStream`	Yes		Yes
`QueryKnowledgeBasesContent`	Yes		Yes
`TextEmbedding`	Yes		Yes
`Rerank`	Yes		Yes
`ListDatabases`					Yes
`ListSchemas`					Yes
`ListTables`					Yes
`DescribeTable`					Yes
`ExecuteStatement`					Yes
`GetSecretValue`					Admin only
`CreateSecret`					Admin only
`DeleteSecret`					Admin only
`ListSecrets`					Admin only
`UseSecret`					Developer only