How do I use --query parameter in aws rds describe-db-instances command

Question

Here is the Synopsis of describe-db-instances

 [--db-instance-identifier <value>]
 [--filters <value>]
 [--cli-input-json <value>]
 [--starting-token <value>]
 [--page-size <value>]
 [--max-items <value>]
 [--generate-cli-skeleton <value>]

I want to know what values in I should use for -db-instance-identifier, --filters, ... ?

If I want to use aws rds describe-db-instances --query, what values I must use in the --query ? Below is the example I got from internet: where are these values from (DBInstanceArn, Engine, DBInstanceIdentifier in --query) ???

aws rds describe-db-instances \
    --query 'DBInstances[*].[DBInstanceArn,Engine,DBInstanceIdentifier]' \
    --output text

And what is the syntax of --query 'DBInstances[*].[DBInstanceArn,Engine,DBInstanceIdentifier]'

Answer 1

The --query parameter is available in most of the aws cli commands. It helps you control the output of the command execution. You might want to read http://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html#controlling-output-filter which details how it works in general.

In the case of aws rds describe-db-instances (you can check doc or run aws rds describe-db-instances help to find out about the output values), the execution of the command will return a long list of attributes for the DB, for each of the DB you run :

{
    "DBInstances": [
        {
            "PubliclyAccessible": true,
            "MasterUsername": "TestDB",
            "MonitoringInterval": 0,
            "LicenseModel": "general-public-license",
            "VpcSecurityGroups": [
                {
                    "Status": "active",
                    "VpcSecurityGroupId": "sg-5a69722b"
                }
            ],
            "CopyTagsToSnapshot": false,
            "OptionGroupMemberships": [
                {
                    "Status": "in-sync",
                    "OptionGroupName": "default:mysql-5-6"
                }
            ],
            "PendingModifiedValues": {
                "MasterUserPassword": "****"
            },
            "Engine": "mysql",
            "MultiAZ": false,
            "DBSecurityGroups": [],
            "DBParameterGroups": [
                {
                    "DBParameterGroupName": "default.mysql5.6",
                    "ParameterApplyStatus": "in-sync"
                }
            ],
            "AutoMinorVersionUpgrade": false,
            "PreferredBackupWindow": "06:52-07:22",
            "DBSubnetGroup": {
                "Subnets": [
                    {
                        "SubnetStatus": "Active",
                        "SubnetIdentifier": "subnet-50dea718",
                        "SubnetAvailabilityZone": {
                            "Name": "us-east-1d"
                        }
                    },
                    {
                        "SubnetStatus": "Active",
                        "SubnetIdentifier": "subnet-c5bba9a0",
                        "SubnetAvailabilityZone": {
                            "Name": "us-east-1b"
                        }
                    },
                    {
                        "SubnetStatus": "Active",
                        "SubnetIdentifier": "subnet-5ff24a05",
                        "SubnetAvailabilityZone": {
                            "Name": "us-east-1a"
                        }
                    },
                    {
                        "SubnetStatus": "Active",
                        "SubnetIdentifier": "subnet-98a39da4",
                        "SubnetAvailabilityZone": {
                            "Name": "us-east-1e"
                        }
                    },
                    {
                        "SubnetStatus": "Active",
                        "SubnetIdentifier": "subnet-42b42c4e",
                        "SubnetAvailabilityZone": {
                            "Name": "us-east-1f"
                        }
                    },
                    {
                        "SubnetStatus": "Active",
                        "SubnetIdentifier": "subnet-4d28a961",
                        "SubnetAvailabilityZone": {
                            "Name": "us-east-1c"
                        }
                    }
                ],
                "DBSubnetGroupName": "default",
                "VpcId": "vpc-1b70fd62",
                "DBSubnetGroupDescription": "default",
                "SubnetGroupStatus": "Complete"
            },
            "ReadReplicaDBInstanceIdentifiers": [],
            "AllocatedStorage": 5,
            "DBInstanceArn": "arn:aws:rds:us-east-1:325979260958:db:testdb",
            "BackupRetentionPeriod": 0,
            "DBName": "TestDB",
            "PreferredMaintenanceWindow": "wed:10:19-wed:10:49",
            "DBInstanceStatus": "creating",
            "IAMDatabaseAuthenticationEnabled": false,
            "EngineVersion": "5.6.35",
            "AvailabilityZone": "us-east-1e",
            "DomainMemberships": [],
            "StorageType": "gp2",
            "DbiResourceId": "db-5VK47WZ6OTS5VEA7OJUF4XH5OI",
            "CACertificateIdentifier": "rds-ca-2015",
            "StorageEncrypted": false,
            "DBInstanceClass": "db.t2.micro",
            "DbInstancePort": 0,
            "DBInstanceIdentifier": "testdb"
        }
    ]
}

You might not be interested into all those elements but want to specifically get subpart of the list. Thats when you will specify the attributes using the --query parameter

I can limit the number of elements to DBInstanceArn, Engine and DBInstanceIdentifier by running the following

$ aws rds describe-db-instances --query 'DBInstances[*].[DBInstanceArn,Engine,DBInstanceIdentifier]'
[
    [
        "arn:aws:rds:us-east-1:325979260958:db:testdb",
        "mysql",
        "testdb"
    ]
]

The syntax used in the query parameter is JMESPath. As the output of the command is a JSon document, it helps you parse it.