<commit_before># Advanced Search

## Overview

An advanced search allows, via Genomic Query Language (GQL), to use structured queries to search for files and cases. 

[![Advanced Search View](images/gdc-data-portal-advanced-search.png)](images/gdc-data-portal-advanced-search.png "Click to see the full image.")

The advanced search provides more filters than the faceted search.

A simple query in GQL (also known as a 'clause') consists of a __field__, followed by an __operator__, followed by one or more __values__. For example, the following simple query will find all files in the "TEST" project:

```
cases.project.primary_site = Brain
```

[![Advanced Search Example](images/gdc-data-portal-advanced-search-example.png)](images/gdc-data-portal-advanced-search-example.png "Click to see the full image.")

Be aware that it is not possible to compare two fields (e.g. disease_type = project.name).

__Note__: GQL is not a database query language. For example, GQL does not have a `SELECT` statement.

### Switch between 'Advanced' and 'Faceted' Search

A query created using 'Faceted Search' will be automatically translated to 'Advanced Search' (i.e. GQL) when clicking on the "Advanced" button.

However, a query created using 'Advanced Search' is not translated to 'Faceted Search'. From the advanced search, click on Basic and you will be redirected to a reset faceted search.

## Use the Advanced Search

When opening the advanced search page (via the Data view), the search field will be automatically populated with facets fileters already applied (if any).

This default query can be removed by pressing "Reset".

Once the query has been entered and is identified as a "Valid Query", click on "Search" to run your query.

## Auto-complete

As a query is being written, the GDC Data Portal will analyse the context and offer a list of "auto-complete".

### Field Auto-complete

The list of auto-complete suggestions includes __all__ the fields authorized in the advanced search matching the user text input. The user has to scroll down to see more fields in the dropdown.

[![Field Auto-complete](images/gdc-data-portal-advanced-search-project.png)](images/gdc-data-portal-advanced-search-project.png "Click to see the full image.")

### Value Auto-complete

The list of auto-complete suggestions includes top 100 values that match the user text input. The user has to scroll down to see more values in the dropdown.

The value auto-complete is not aware of the general context of the query, the system will display all available values in GDC for the selected field.
It means the query could return 0 result depending of other filters.

[![Value Auto-complete](images/gdc-data-portal-advanced-search-value.png)](images/gdc-data-portal-advanced-search-value.png "Click to see the full image.")

__Note__: Quotes are automatically added to the value if it contains spaces.

## Setting Precedence of Operators

You can use parentheses in complex GQL statements to enforce the precedence of operators.

For example, if you want to find all the open files in TCGA program as well as the files in TARGET program, you can use parentheses to enforce the precedence of the boolean operators in your query, i.e.:

```
(files.access = open and cases.project.program.name = TCGA) or cases.project.program.name = TARGET
```

__Note__: Without parentheses, the statement will be evaluated left-to-right.

## Keywords

A GQL keyword is a word that joins two or more clauses together to form a complex GQL query.

**List of Keywords:**

*   AND
*   OR  

__Note__: parentheses can be used to control the order in which clauses are executed.

### AND Keyword

Used to combine multiple clauses, allowing you to refine your search.

Examples:

```Example
# Find all open files in breast cancer

cases.project.primary_site = Breast and files.access = open
```

```Example
# Find all open files in breast cancer and data type is copy number variation

cases.project.primary_site = Breast and files.access = open and files.data_type = "Copy number variation"
```

### OR Keyword

Used to combine multiple clauses, allowing you to expand your search.

__Note__: __IN__ keyword can be an alternative to OR and result in simplified queries.

Examples:

*   Find all files that are raw sequencing data or raw microarray data:
<commit_msg>More updated on data portal user guide<commit_after># Advanced Search

## Overview

An advanced search allows, via Genomic Query Language (GQL), to use structured queries to search for files and cases. 

[![Advanced Search View](images/gdc-data-portal-advanced-search.png)](images/gdc-data-portal-advanced-search.png "Click to see the full image.")

The advanced search provides more filters than the faceted search.

A simple query in GQL (also known as a 'clause') consists of a __field__, followed by an __operator__, followed by one or more __values__. For example, the following simple query will find all files in the "TEST" project:

```
cases.project.primary_site = Brain
```

[![Advanced Search Example](images/gdc-data-portal-advanced-search-example.png)](images/gdc-data-portal-advanced-search-example.png "Click to see the full image.")

Be aware that it is not possible to compare two fields (e.g. disease_type = project.name).

__Note__: GQL is not a database query language. For example, GQL does not have a `SELECT` statement.

### Switch between 'Advanced' and 'Faceted' Search

A query created using 'Faceted Search' will be automatically translated to 'Advanced Search' (i.e. GQL) when clicking on the "Advanced" button.

However, a query created using 'Advanced Search' is not translated to 'Faceted Search'. From the advanced search, click on Basic and you will be redirected to a reset faceted search.

## Use the Advanced Search

When opening the advanced search page (via the Data view), the search field will be automatically populated with facets fileters already applied (if any).

This default query can be removed by pressing "Reset".

Once the query has been entered and is identified as a "Valid Query", click on "Search" to run your query.

## Auto-complete

As a query is being written, the GDC Data Portal will analyse the context and offer a list of "auto-complete".

### Field Auto-complete

The list of auto-complete suggestions includes __all__ the fields authorized in the advanced search matching the user text input. The user has to scroll down to see more fields in the dropdown.

[![Field Auto-complete](images/gdc-data-portal-advanced-search-project.png)](images/gdc-data-portal-advanced-search-project.png "Click to see the full image.")

### Value Auto-complete

The list of auto-complete suggestions includes top 100 values that match the user text input. The user has to scroll down to see more values in the dropdown.

The value auto-complete is not aware of the general context of the query, the system will display all available values in GDC for the selected field.
It means the query could return 0 result depending of other filters.

[![Value Auto-complete](images/gdc-data-portal-advanced-search-value.png)](images/gdc-data-portal-advanced-search-value.png "Click to see the full image.")

__Note__: Quotes are automatically added to the value if it contains spaces.

## Setting Precedence of Operators

You can use parentheses in complex GQL statements to enforce the precedence of operators.

For example, if you want to find all the open files in TCGA program as well as the files in TARGET program, you can use parentheses to enforce the precedence of the boolean operators in your query, i.e.:

```
(files.access = open and cases.project.program.name = TCGA) or cases.project.program.name = TARGET
```

__Note__: Without parentheses, the statement will be evaluated left-to-right.

## Keywords

A GQL keyword is a word that joins two or more clauses together to form a complex GQL query.

**List of Keywords:**

*   AND
*   OR  

__Note__: parentheses can be used to control the order in which clauses are executed.

### AND Keyword

Used to combine multiple clauses, allowing you to refine your search.

Examples:

* Find all open files in breast cancer

```
cases.project.primary_site = Breast and files.access = open
```

* Find all open files in breast cancer and data type is copy number variation

```
cases.project.primary_site = Breast and files.access = open and files.data_type = "Copy number variation"
```

### OR Keyword

Used to combine multiple clauses, allowing you to expand your search.

__Note__: __IN__ keyword can be an alternative to OR and result in simplified queries.

Examples:

*   Find all files that are raw sequencing data or raw microarray data:

{'fraction_non_alphanumeric': 0.0711070068105737, 'fraction_numerical': 0.0009234676209165416, 'mean_word_length': 4.404865876481597, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1781862', 'n_tokens_mistral': 2359, 'n_tokens_neox': 2254, 'n_words': 1186}