Azure Cosmos DB에서 가져오기

중요

Machine Learning Studio(클래식)에 대한 지원은 2024년 8월 31일에 종료됩니다. 해당 날짜까지 Azure Machine Learning으로 전환하는 것이 좋습니다.

2021년 12월 1일부터 새로운 Machine Learning Studio(클래식) 리소스를 만들 수 없습니다. 2024년 8월 31일까지는 기존 Machine Learning Studio(클래식) 리소스를 계속 사용할 수 있습니다.

• ML Studio(클래식)에서 Azure Machine Learning으로 기계 학습 프로젝트 이동에 대한 정보를 참조하세요.
• Azure Machine Learning에 대한 자세한 정보.

ML Studio(클래식) 설명서는 사용 중지되며 나중에 업데이트되지 않을 수 있습니다.

이 문서에서는 Machine Learning Studio(클래식)의 데이터 가져오기 모듈을 사용하여 기계 학습 실험에 사용하기 위해 Azure Cosmos DB에서 데이터를 가져오는 방법을 설명합니다.

참고

적용 대상: Machine Learning Studio(클래식) 전용

유사한 끌어서 놓기 모듈은 Azure Machine Learning 디자이너에서 사용할 수 있습니다.

Azure Cosmos DB는 유연한 데이터 모델을 사용하여 NoSQL 데이터베이스 스토리지를 지원합니다. 기계 학습을 위해 이 데이터 저장소의 SQL API를 사용하면 빠르고 예측 가능한 성능, 자동 크기 조정, 전역 배포 및 풍부한 쿼리 기능이 있습니다.

Azure SQL Database 함께 이 옵션을 사용하면 들어오는 데이터 세트를 동적으로 필터링할 수 있습니다.

작동 방법 알아보기: Azure Cosmos DB에 대해 알아보기

• Azure Cosmos DB의 데이터를 사용하여 기계 학습을 시작하려면 관련 문서 컬렉션이 포함된 기존 Azure Cosmos DB 계정에 액세스할 수 있어야 합니다.

참고

Machine Learning Studio(클래식)의 사용자 인터페이스는 여전히 여러 위치에서 DocumentDB라는 이름을 사용합니다. 따라서 API가 Azure Cosmos DB에 통합되어 있더라도 DocumentDB에 대한 참조를 계속 볼 수 있습니다.

Azure Cosmos DB에서 데이터 가져오기를 사용하는 방법

스키마가 예상대로 작동하는지 확인하려면 가져오기 전에 데이터를 프로파일링하는 것이 좋습니다. 가져오기 프로세스는 몇 개의 헤드 행을 검사하여 스키마를 확인하지만 이후 행에는 추가 열 또는 오류를 일으키는 데이터가 포함될 수 있습니다.

마법사를 사용하여 데이터 가져오기

이 모듈에는 스토리지 옵션을 선택하고, 기존 구독 및 계정 중에서 선택하고, 모든 옵션을 신속하게 구성하는 데 도움이 되는 새 마법사가 있습니다.

1. 데이터 가져오기 모듈을 실험에 추가합니다. 데이터 입력 및 출력 아래에서 모듈을 찾을 수 있습니다.

2. 데이터 가져오기 마법사 시작을 클릭하고 프롬프트를 따릅니다.

3. 구성이 완료되면 실제로 데이터를 실험에 복사하려면 모듈을 마우스 오른쪽 단추로 클릭하고 [선택됨 실행]을 선택합니다.

팁

기존 데이터 연결을 편집해야 하는 경우 마법사는 모든 이전 구성 세부 정보를 로드합니다. 처음부터 다시 시작할 필요가 없습니다.

데이터 가져오기 모듈에서 수동으로 속성 설정

다음 단계에서는 가져오기 원본을 수동으로 구성하는 방법을 설명합니다.

1. 데이터 가져오기 모듈을 실험에 추가합니다. 이 모듈은 데이터 입력 및 출력 범주에서 찾을 수 있습니다.

2. 데이터 원본의 경우 Azure DocumentDB를 선택합니다.

   문서 데이터베이스에 대한 연결 정보를 제공해야 할 수도 있습니다.

   팁

   나중에 변경할 Machine Learning Studio(클래식)에서 옵션의 이름을 찾습니다. 가져오기 기능은 이름 변경의 영향을 받지 않았습니다.

3. 엔드포인트 URL의 경우 Azure Portal에서 키를 클릭하고 페이지 맨 위에 있는 URI 필드의 내용을 복사합니다.

4. 데이터베이스 ID의 경우 사용할 데이터베이스의 이름을 붙여넣습니다.

   Azure Portal에서 데이터베이스 이름을 얻으려면 문서 탐색기를 클릭합니다. 이 창에서 데이터베이스 및 컬렉션 목록을 볼 수 있습니다.

5. DocumentDB 키의 경우 계정에 대한 액세스 키를 붙여넣습니다.

   키를 찾으려면 키를 클릭한 다음 기본 키 또는 보조 키 필드의 콘텐츠를 복사합니다.

6. 컬렉션 ID의 경우 지정된 CosmosDB 데이터베이스에 표시된 대로 컬렉션의 이름을 입력합니다.

7. SQL 쿼리 및 SQL 쿼리 매개 변수 옵션을 사용하여 데이터에 대한 SQL 쿼리 및 필터 조건을 정의합니다.

   SQL 쿼리의 경우 컬렉션에서 검색할 데이터를 정의하는 쿼리를 입력합니다. 쿼리 탐색기를 사용하여 CosmosDB 쿼리를 미리 만들고 테스트하는 것이 좋습니다.

   SQL 쿼리 매개 변수의 경우 반환된 데이터를 동적으로 필터링하는 데 사용할 수 있는 JSON 형식의 식을 제공합니다. 일반적으로 웹 서비스의 일부로 실험을 실행할 때 매개 변수 값의 실제 값을 입력합니다.

   매개 변수를 사용하는 경우 필터 변수 이름을 SQL 쿼리 텍스트 상자에 지정된 WHERE 절의 일부로 정의해야 합니다.

   필터 식을 지정하지 않으면 기본적으로 값이 "{}"로 설정되고 모든 레코드가 반환됩니다.

   CosmosDB의 SQL 쿼리에 대한 예제, 알려진 문제 및 추가 조언은 기술 정보 섹션을 참조하세요.

8. 기존 결과를 다시 사용하려면 캐시된 결과 사용 옵션을 선택합니다.

   이 옵션을 선택 취소하면 데이터가 같은지 여부에 관계없이 실험이 실행 될 때마다 원본에서 데이터를 읽습니다.

   Machine Learning 캐시된 데이터를 CosmosDB 계정의 데이터와 비교할 수 없습니다. 따라서 Machine Learning 증분 업데이트를 수행할 방법이 없습니다.

   데이터가 변경될 때만 다시 가져오려면 Azure Data Factory 같은 다른 애플리케이션에서 해당 논리를 정의해야 합니다. 자세한 내용은 Azure Data Factory 사용하여 Azure Cosmos DB에서 데이터 이동을 참조하세요.

9. 실험을 실행하거나 데이터 가져오기 모듈만 선택하고 선택한 실행을 클릭합니다.

결과

모듈 또는 실험을 실행한 후 모듈의 출력을 마우스 오른쪽 단추로 클릭하여 결과를 테이블 형식으로 시각화할 수 있습니다.

Machine Learning 작업 영역에서 이 데이터의 스냅샷을 데이터 세트로 캡처하려면 모듈의 출력을 마우스 오른쪽 단추로 클릭하고 데이터 세트로 저장을 선택할 수 있습니다. 그러나 이렇게 하면 가져올 때 사용할 수 있는 데이터만 캡처됩니다. 데이터가 자주 변경될 것으로 예상되는 경우 필요에 따라 데이터 가져오기 를 다시 실행합니다.

예

Azure Cosmos DB를 기계 학습을 위한 데이터 원본으로 사용하는 방법에 대한 자세한 연습은 Azure AI 갤러리를 참조하세요.

• Azure Cosmos DB에 대한 SQL 쿼리: 이 문서에서는 Azure Cosmos DB 데이터에 대해 SQL 쿼리를 수행하는 방법을 설명합니다.

기술 정보

이 섹션에는 일반적인 질문에 대한 고급 구성 옵션 및 답변이 포함되어 있습니다.

단순 및 매개 변수가 있는 쿼리의 예

고도가 10000피트 미만인 화산의 데이터만 사용하려는 경우를 가정해 보겠습니다.

단순 쿼리

SQL 쿼리 텍스트 상자에 다음 쿼리를 붙여넣습니다.Select * from volcanodb where volcanodb.Elevation < 10000

이 경우 필터 식의 값이 "{}"로 설정되고 모든 레코드가 반환됩니다.

매개 변수가 있는 쿼리

특정 국가와 관련된 화산 데이터만 가져오기 위해 국가 값을 런타임에 쿼리에 전달되는 매개 변수로 지정할 수 있습니다. 이렇게 하려면 다음을 변경해야 합니다.

1. SQL 쿼리 텍스트 상자에서 필드에 적용할 변수를 Country SQL 쿼리의 일부로 정의합니다.

   Select * from volcanodb where volcanodb.Country = @param1

2. SQL 쿼리 매개 변수 텍스트 상자에서 다음과 같이 매개 변수 이름과 해당 값을 JSON 형식으로 지정합니다.

   {"@param1":"Turkey"}

리소스

기존 문서 저장소가 없는 경우 시작하려면 다음 문서를 참조하세요.

• Azure Cosmos DB: .NET 및 Azure Portal을 사용하여 SQL API 웹앱 빌드

• 빠른 시작: .NET 콘솔 앱을 빌드하여 Azure Cosmos DB SQL API 리소스 관리

• Azure Cosmos DB 마이그레이션 도구

데이터 마이그레이션 및 쿼리 구문 도움말

JSON 데이터 저장소의 쿼리 샘플은 Azure Cosmos DB 쿼리 치트 시트를 다운로드합니다.

Azure Cosmos DB에 콘텐츠를 업로드해야 하는 경우 Azure Cosmos DB 마이그레이션 도구를 사용하는 것이 좋습니다. 데이터의 유효성을 검사, 업로드 및 인덱싱합니다. 이 도구는 MongoDB, Amazon DynamoDB, HBase, SQL Server 데이터베이스 및 CSV 파일을 비롯한 여러 원본을 지원합니다.

스키마 없는 쿼리 사용

데이터가 일관되고 예측 가능한 경우 다음과 같은 SELECT * FROM <document collection>간단한 SQL 구문을 사용할 수 있습니다. 반환할 정확한 특성의 이름을 지정하지 않았기 때문에 스키마 없는 쿼리 라고 합니다. 이러한 쿼리는 지정된 컬렉션의 모든 필드와 모든 행을 반환합니다.

그러나 스키마를 지정하지 않으면 문서에 일관성이 없는 스키마가 있는 경우 예기치 않은 결과 또는 런타임 오류가 발생할 수 있습니다. 이는 데이터 가져오기 모듈이 다음과 같이 미리 정해진 수의 행을 기반으로 스키마를 유추하려고 하기 때문입니다.

1. 특성을 지정하지 않으면 모듈은 CosmosDB 데이터베이스의 첫 번째 행을 검색합니다.
2. 모듈은 특성에 따라 열 이름을 만들고 예제 행을 기반으로 하는 열 데이터 형식을 추측합니다.
3. 이후 행에 새 특성이나 다른 특성이 포함된 경우 런타임 오류가 생성됩니다.

따라서 CosmosDB 데이터 저장소에서 반환할 특성과 값을 항상 지정하는 것이 좋습니다. 예를 들어 구문을 사용하는 SELECT * 대신 다음과 같이 쿼리에서 검색된 모든 특성의 이름을 지정하는 것이 좋습니다.

SELECT MyTable.Gender, MyTable.Age, MyTable.Name FROM <document collection>

모듈 매개 변수

다음 표에는 Azure Cosmos DB 옵션에 적용할 수 있는 데이터 가져오기 모듈에 대한 매개 변수만 포함되어 있습니다.

Name	범위	Type	필수	기본값	설명
데이터 원본	list	HTTP	필수	없음	데이터 원본은 HTTP, FTP, 익명 HTTPS 또는 FTPS, Azure BLOB Storage의 파일, Azure 테이블, Azure SQL Database, Hive 테이블, OData 엔드포인트 또는 Azure Cosmos dB일 수 있습니다.
엔드포인트 URL	any	문자열	필수	없음	Azure Cosmos DB 서버에 대한 URI 제공
데이터베이스 ID	any	문자열	필수	없음	Azure Cosmos DB 데이터베이스의 이름을 입력합니다.
DocumentDB 키	any	SecureString	필수	없음	Azure Cosmos DB 계정에 유효한 API 키 제공
컬렉션 ID	any	문자열	필수	없음	Azure Cosmos DB 데이터베이스에서 컬렉션의 이름을 입력합니다.
SQL 쿼리	any	문자열	필수	없음	Azure Cosmos DB 데이터 저장소에서 반환할 레코드를 지정하는 SQL 쿼리

출력

Name	유형	설명
결과 데이터 집합	데이터 테이블	다운로드한 데이터가 포함된 데이터 집합입니다.

예외

예외	설명
오류 0003	입력 중 하나 이상이 null이거나 비어 있으면 예외가 발생합니다.
오류 0029	잘못된 URI가 전달되면 예외가 발생합니다.
오류 0002	하나 이상의 매개 변수를 구문 분석할 수 없거나 지정된 형식을 대상 방법에 필요한 형식으로 변환할 수 없으면 예외가 발생합니다.
오류 0048	파일을 열 수 없으면 예외가 발생합니다.
오류 0049	파일을 구문 분석할 수 없으면 예외가 발생합니다.

Studio(클래식) 모듈과 관련된 오류 목록은 Machine Learning 오류 코드를 참조하세요.

API 예외 목록은 Machine Learning REST API 오류 코드를 참조하세요.

참고 항목

데이터 가져오기
데이터 내보내기
HTTP를 통해 웹 URL에서 가져오기
Hive 쿼리에서 가져오기
Azure SQL Database에서 가져오기
Azure Blob Storage에서 가져오기
데이터 피드 공급자에서 가져오기
온-프레미스 SQL Server 데이터베이스에서 가져오기